NetBird auf Unifi UDM installieren: Automatisches Setup-Skript

1. Einleitung

Die Integration einer Ubiquiti Dream Machine (UDM, UDM Pro, UDM SE) in ein NetBird Mesh-Netzwerk erfordert aufgrund des geschlossenen UniFi-Betriebssystems manuelle Anpassungen. Da UniFi OS ab Version 3.x auf Debian basiert, ist eine Installation jedoch gut moeglich.

Ziel dieses Tutorials ist die Installation von NetBird als systemd-Service auf der UDM. Dabei wird ein Skript verwendet, das spezifische Anpassungen fuer den aelteren Linux-Kernel der UDM vornimmt (Legacy Routing).

Voraussetzungen:

• Unifi UDM / Pro / SE mit UniFi OS Version 3.0.0 oder hoeher
• SSH-Zugriff auf die UDM aktiviert
• Ein gueltiger NetBird Setup-Key

2. Ueberblick

Wir nutzen ein Shell-Skript, das den NetBird-Client herunterlaedt, installiert und die notwendigen Umgebungsvariablen setzt, damit der Client trotz fehlender moderner Kernel-Features stabil laeuft.

• Automatischer Download der aktuellsten ARM64-Version
• Einrichtung des Systemd-Dienstes
• Konfiguration des Legacy-Routing-Modus

3. Schritt-fuer-Schritt Anleitung

1. Verbindung per SSH herstellen
   Loggen Sie sich via Terminal auf Ihrer UDM ein.

ssh root@<IP-Ihrer-UDM>

2. Installations-Skript erstellen
   Erstellen Sie eine neue Datei namens install.sh im Verzeichnis /data/ (dieses Verzeichnis ueberlebt Reboots).

Kopieren Sie den folgenden Code in die Datei. Das Skript prüft die Firmware-Version, laedt NetBird herunter und konfiguriert den Dienst so, dass NB_USE_LEGACY_ROUTING aktiv ist.

#!/bin/bash

set -e

# Pruefung auf Firmware Version 3.0.0+
if test $(ubnt-device-info firmware) \< "3.0.0"; then
    echo "Try the other UDM setup script for 1.x: https://git.shivering-isles.com/-/snippets/19" >&2
    exit 1
fi

mkdir -p /data/netbird
cd /data/netbird

# Backup existierender Installationen
if [[ -e ./netbird ]]; then
    mv ./netbird ./netbird.old
fi

# Download der neuesten Version (benoetigt jq und curl)
NETBIRD_VERSION="$(curl -s https://api.github.com/repos/netbirdio/netbird/releases/latest | jq -r ".tag_name")"
curl -L https://github.com/netbirdio/netbird/releases/download/${NETBIRD_VERSION}/netbird_${NETBIRD_VERSION//v}_linux_arm64.tar.gz | tar xvzf -

# Installation des Dienstes
./netbird service install || true 

# Konfiguration fuer Unifi Kernel (Legacy Routing)
mkdir -p /etc/systemd/system/netbird.service.d/
cat >/etc/systemd/system/netbird.service.d/legacy.conf <<EOF
[Service]
Environment="NB_USE_LEGACY_ROUTING=true"
Environment="NB_DISABLE_CUSTOM_ROUTING=true"
EOF

# Dienst neu laden und starten
systemctl daemon-reload

if systemctl is-active netbird.service; then
    systemctl restart netbird.service
fi

if ! systemctl is-enabled netbird.service; then
    systemctl enable --now netbird.service
fi

3. Skript ausfuehren
   Machen Sie das Skript ausfuehrbar und starten Sie die Installation.

chmod +x /data/install.sh
/data/install.sh

[BILD 2: Terminal-Ausgabe waehrend das Skript durchlaeuft]

4. UDM registrieren
   Nach erfolgreicher Installation muss der Client mit Ihrem NetBird-Account verknuepft werden. Nutzen Sie dazu Ihren Setup-Key.

/data/netbird/netbird -k <IHR-SETUP-KEY> up

4. Wichtige Hinweise & Stolperfallen

Abhaengigkeiten: Das Skript nutzt jq zum Parsen der GitHub-API. Sollte der Befehl nicht gefunden werden, installieren Sie ihn via apt-get update && apt-get install jq (nur moeglich auf UDM OS 3.x).

Kernel-Limitierung: Die Zeilen NB_USE_LEGACY_ROUTING=true sind essenziell. Der Kernel der UDM ist oft veraltet und unterstuetzt moderne eBPF-Features nicht, weshalb NetBird ohne diesen «Legacy»-Modus nicht starten oder keine Verbindung aufbauen wuerde.

5. Ergebnis & Fazit

Die Unifi Dream Machine ist nun als Peer im NetBird-Netzwerk sichtbar. Durch die Installation im /data Verzeichnis und die Einrichtung als systemd-Service bleibt die Installation auch nach einem Neustart aktiv.

Sie koennen nun auf interne Ressourcen hinter der UDM zugreifen oder die UDM als Exit-Node konfigurieren.