UniFi‑Switch ohne SSH hinter NAT‑Firewall adoptieren per DHCP‑Option 43

Diese Anleitung beschreibt Schritt für Schritt, wie du einen UniFi-Switch (z. B. USW-Flex-Mini), der kein SSH bietet, mit einem Controller koppelst, der sich hinter einer NAT-Firewall befindet.
Der Trick: Wir geben dem Switch die Controller-IP direkt via DHCP Option 43.

1 · Netzdesign / Topologie

# uplink-LAN (10.0.0.0/24)
Internet/Router ──> eth0 (10.0.0.2/24) [Debian]  \
                                                   \ NAT (Masquerade)
                            eth1 (172.0.0.1/24)    [Debian] ──> UniFi-Switch (DHCP, z. B. 172.0.0.10)

# Controller liegt im Uplink-LAN: 10.0.0.1

• eth1 bekommt ein separates /24 (hier 172.0.0.0/24), damit der Switch sofort erkennt, dass 10.0.0.1 außerhalb seines Netzes liegt und das Gateway nutzt.
• NAT / Masquerade auf dem Debian-Host erlaubt dem Switch, den Controller über eth0 zu erreichen.

2 · Interface- und System-Basis

# /etc/network/interfaces – Ausschnitt
auto eth1
iface eth1 inet static
    address 172.0.0.1
    netmask 255.255.255.0

# IP-Forwarding permanent einschalten (als root)
echo "net.ipv4.ip_forward = 1" > /etc/sysctl.d/99-nat.conf
sysctl -p /etc/sysctl.d/99-nat.conf

# Einfaches Masquerading für das Subnetz 172.0.0.0/24 (als root)
iptables -t nat -A POSTROUTING -s 172.0.0.0/24 -o eth0 -j MASQUERADE

# Regeln persistent speichern – z. B. via iptables-persistent / netfilter-persistent

2.3 · Forwarding erlauben (falls dein Host ein “Sicherheitsbunker” ist)

Einige Systeme haben die Standard-Policy der FORWARD-Chain auf DROP. Dann reicht Masquerading allein nicht: Pakete werden zwar NAT-ted, aber beim Forwarding verworfen.

Prüfen:

iptables -L FORWARD -n -v

Wenn dort oben policy DROP steht (und die Zähler hochlaufen), erlaube Forwarding für dein Switch-Netz:

# Forwarding von "Switch-Seite" (eth1) ins Uplink (eth0) erlauben
iptables -I FORWARD 1 -i eth1 -o eth0 -s 172.0.0.0/24 -m conntrack --ctstate NEW,ESTABLISHED,RELATED -j ACCEPT

# Rückverkehr (Replies) wieder zurück zur Switch-Seite erlauben
iptables -I FORWARD 2 -i eth0 -o eth1 -d 172.0.0.0/24 -m conntrack --ctstate ESTABLISHED,RELATED -j ACCEPT

Hinweis: Wenn deine Interface-Namen anders heißen (z. B. enp0s31f6 statt eth1 oder wlp0s20f3 statt eth0), ersetze sie entsprechend.

Danach ggf. Regeln persistent speichern, sonst sind sie nach dem Reboot weg.

3 · ISC-DHCP-Server installieren & konfigurieren

# als root
apt-get update
apt-get install isc-dhcp-server

3.1 Server-Interface festlegen

# /etc/default/isc-dhcp-server
INTERFACESv4="eth1"

3.2 /etc/dhcp/dhcpd.conf

subnet 172.0.0.0 netmask 255.255.255.0 {
  range 172.0.0.10 172.0.0.50;
  option routers 172.0.0.1;
  option broadcast-address 172.0.0.255;

  # *** UniFi-Magie: DHCP Option 43 ***
  # 01  -> Sub-Option 1  (Controller-IP)
  # 04  -> Länge in Bytes (4)
  # 0a 00 00 01 -> 10.0.0.1 in Hex
  option vendor-encapsulated-options 01:04:0a:00:00:01;

  # DNS für Clients (hier Cloudflare)
  option domain-name-servers 1.1.1.1, 1.0.0.1;
}

Jedes Oktett der Controller-IP in Hex schreiben:

systemctl enable --now isc-dhcp-server
systemctl status isc-dhcp-server

4 · Firewall / Ports

Port	Protokoll	Zweck
8080	TCP	Inform & Adoption
3478	UDP	STUN
10001	UDP	Discovery (alt)
8443	TCP	Controller-GUI/API

Achte darauf, dass diese Ports von 172.0.0.0/24 über NAT zu 10.0.0.1 passieren dürfen.

5 · Switch anschließen & adoptieren

1. Switch auf Werkseinstellungen zurücksetzen (Reset-Taster > 5 s).
2. An eth1 des Debian-Hosts stecken.
3. Mit tcpdump überprüfen, dass Option 43 im DHCPACK auftaucht:
   

   tcpdump -ni eth1 port 67 or port 68 | grep -i "Vendor specific"

4. Controller-UI öffnen https://10.0.0.1:8443 ➜ Devices » Pending Adoption.
   Gerät erscheint? → Adopt.

Debugging-Checks

# Kommt der Switch raus?
ping -c3 10.0.0.1

# Siehst du Inform-Traffic?
tcpdump -ni eth1 host 10.0.0.1 and port 8080

# Controller-Logs (Pfad je nach Installation/Container ggf. anders)
tail -f /usr/lib/unifi/logs/server.log

Anhang A · IP-Adresse in Hexadezimal umrechnen – Schritt für Schritt

Warum überhaupt Hex?
DHCP-Option 43 braucht die Controller-IP als rohe Bytefolge. Bytes schreibt man in der Netzwerktechnik üblich in Hexadezimal (“Hex”). Ein Byte kann Werte von 00 bis ff (= 0 – 255 dezimal) annehmen.

1 · Vier Oktette der IP aufschreiben

Beispiel-IP unseres Controllers:

10 . 0 . 0 . 1

2 · Jedes Oktett einzeln nach Hex konvertieren

Dezimal	Rechenweg	Hexadezimal
10	10 / 16 = 0 Rest 10 → 0 = 0, 10 = a	0a
0	0 = 0 → 00	00
0	0 = 0 → 00	00
1	1 / 16 = 0 Rest 1 → 01	01

Merksatz: Wenn das Ergebnis nur ein Hex-Zeichen hat (z. B. a), wird immer eine führende Null ergänzt → 0a. So entstehen exakt vier Byte.

3 · Bytes zusammenfügen

0a 00 00 01

4 · In DHCP-Option 43 einbauen

Die Struktur lautet: 01 : 04 : <IP-Hex-Byte1> : <IP-Hex-Byte2> : <IP-Hex-Byte3> : <IP-Hex-Byte4>

• 01 = Sub-Option 1 (Controller-IP)
• 04 = Länge (4 Byte)
• 0a:00:00:01 = die vier Hex-Bytes von oben

option vendor-encapsulated-options 01:04:0a:00:00:01;

Schnell-Check mit Python

Für größere Netze lohnt es sich, nicht zu rechnen, sondern einen Einzeiler zu nutzen:

python3 -c 'import sys,ipaddress; \
print(":".join(f"{b:02x}" for b in ipaddress.IPv4Address(sys.argv[1]).packed))' \
10.0.0.1

Ausgabe: 0a:00:00:01 – genau wie von Hand.

Spickzettel 0 – 255 → Hex

Dez	Hex	Dez	Hex	Dez	Hex	Dez	Hex
0	00	16	10	128	80	240	f0
1	01	32	20	144	90	241	f1
2	02	64	40	160	a0	250	fa
3	03	100	64	176	b0	255	ff

Damit können auch Azubis ohne Vorwissen eine IP schnell in Hex umbrechen und die Option 43 korrekt setzen.