VLANs auf Ubiquiti-Switches per SSH konfigurieren BookStack-Anleitung · Version 1.0 · Stand: 30. Juli 2026 · Zielgruppe: Administratoren und Homelab-Betreiber Geltungsbereich Diese Anleitung gilt für Ubiquiti-Switches, die über SSH eine Cisco-artige FastPath-/EdgeSwitch-CLI mit Befehlen wie vlan database, configure, switchport mode access und switchport mode trunk bereitstellen. Sie ist keine Behauptung, dass jeder UniFi-Switch, jede Firmware oder jede Produktfamilie dieselben Befehle unterstützt. Vor Änderungen wird die verfügbare CLI-Hilfe geprüft. Wichtiger Hinweis zu UniFi Network Bei einem durch UniFi Network verwalteten Switch können manuelle SSH-Änderungen bei der nächsten Provisionierung überschrieben werden. Für dauerhaft unterstützte Konfigurationen ist dort der Port Manager beziehungsweise ein Ethernet-Portprofil der vorgesehene Weg. Die SSH-CLI eignet sich vor allem zur Diagnose, für Laborumgebungen und für Geräte, deren lokale CLI und Speichermethode ausdrücklich geprüft wurden. Inhalt 1. Grundlagen 2. VLAN-Planung 3. Vorbereitung und Sicherung 4. SSH und CLI öffnen 5. Mehrere VLANs erstellen 6. Access-Port konfigurieren 7. Trunk-Port konfigurieren 8. Typische Anschlussszenarien 9. Konfiguration prüfen 10. Änderungen speichern 11. Rückbau und Notfallplan 12. Häufige Fehler 13. Entsprechung in UniFi Network 14. Kurzreferenz 15. Quellen 1. Grundlagen Ein VLAN trennt ein physisches Ethernet-Netz logisch in mehrere Layer-2-Netze. Geräte in unterschiedlichen VLANs teilen sich zwar möglicherweise denselben Switch, befinden sich aber in getrennten Broadcast-Domänen. Kommunikation zwischen VLANs benötigt einen Router, eine Firewall oder einen Layer-3-Switch mit passenden Regeln. Begriff Bedeutung VLAN-ID / VID Numerische Kennung eines VLANs. Bei der hier beschriebenen CLI liegt der nutzbare Bereich typischerweise bei 1 bis 4093; VLAN 1 ist meist das Default-VLAN. Untagged / unmarkiert Ein Ethernet-Frame verlässt den Port ohne 802.1Q-VLAN-Tag. Normale Endgeräte erwarten üblicherweise ungetaggte Frames. Tagged / markiert Der Frame trägt ein 802.1Q-Tag mit VLAN-ID. Das Gegenüber muss VLAN-Tags verstehen. Access-Port Transportiert genau ein VLAN ungetaggt. Geeignet für PCs, Drucker, Kameras und andere nicht VLAN-fähige Endgeräte. Trunk-Port Transportiert mehrere VLANs. Ein VLAN kann als Native VLAN ungetaggt übertragen werden; weitere VLANs werden getaggt. Native VLAN / PVID VLAN, dem ungetaggte eingehende Frames zugeordnet werden. Auf einem Trunk ist es üblicherweise zugleich das ungetaggt ausgehende VLAN. Allowed VLANs Liste der VLANs, die über einen Trunk transportiert werden dürfen. Merksatz Access bedeutet: ein VLAN, ungetaggt. Trunk bedeutet: mehrere VLANs, normalerweise ein Native VLAN ungetaggt und weitere VLANs getaggt. 2. VLAN-Planung Vor der ersten Eingabe wird eine Port- und VLAN-Tabelle erstellt. Das Beispiel ist absichtlich generisch: VLAN-ID Name Beispielzweck Gateway/DHCP 10 Management Switches, Access Points, Verwaltungszugänge Auf Router/Firewall konfigurieren 110 Clients Arbeitsplätze und normale Endgeräte Auf Router/Firewall konfigurieren 120 Voice VoIP-Telefone Auf Router/Firewall konfigurieren 130 Guest Gäste oder isolierte Geräte Auf Router/Firewall konfigurieren Beispielhafter Portplan: Port Rolle Native/Untagged Tagged 0/5 Access-Port für Client VLAN 110 keine 0/12 Access-Port für Telefon oder Endgerät VLAN 120 keine 0/24 Access Point VLAN 10 VLAN 110 und 130 0/48 Uplink zu Router oder weiterem Switch VLAN 10 VLAN 110, 120 und 130 Der Switch ersetzt keinen Router Das Anlegen eines VLANs auf dem Switch erzeugt weder ein IP-Subnetz noch DHCP noch Firewallregeln. Router oder Firewall müssen für jedes benötigte VLAN eine passende Schnittstelle beziehungsweise Subinterface besitzen. 3. Vorbereitung und Sicherung 3.1 Notfallzugang vorbereiten Nicht zuerst den Port ändern, über den die aktuelle SSH-Sitzung läuft. Wenn möglich einen zweiten Verwaltungsweg, Konsolenzugang oder einen unveränderten Management-Port bereithalten. Uplink und Management-VLAN erst ändern, nachdem Access- und Trunk-Konzept auf beiden Seiten feststehen. Bei entfernten Standorten eine Rückfallmöglichkeit vor Ort einplanen. Ein falsches Native VLAN ist ein sehr effizienter Weg, sich selbst auszusperren. 3.2 Ist-Zustand dokumentieren Vor Änderungen diese Befehle ausführen und die Ausgabe lokal speichern: show version show network show vlan brief show interfaces status all show running-config Nicht jedes Modell unterstützt jede Anzeige. Ein unbekannter show-Befehl ist kein Anlass, kreativ schreibende Befehle auszuprobieren; stattdessen mit show ? die lokale Hilfe verwenden. 4. SSH und CLI öffnen 4.1 SSH-Verbindung herstellen ssh @ 4.2 Lokale Switch-CLI öffnen Auf vielen UniFi-USW-Firmwares landet man zunächst in einer Linux-Shell: cli enable Auf EdgeSwitch-Systemen kann SSH bereits direkt die Switch-CLI öffnen. Dann ist cli nicht erforderlich. 4.3 Syntax vorab prüfen ? vlan database ? configure interface ? exit Abbruchkriterium Fehlen vlan database, switchport mode access oder switchport mode trunk in der lokalen Hilfe, darf diese Befehlsfolge nicht blind auf das Gerät übertragen werden. Ubiquiti verwendet je nach Produktfamilie unterschiedliche CLIs. 5. Mehrere VLANs erstellen 5.1 VLAN-Datenbank öffnen vlan database 5.2 VLANs einzeln anlegen und benennen vlan 10 vlan name 10 Management vlan 110 vlan name 110 Clients vlan 120 vlan name 120 Voice vlan 130 vlan name 130 Guest exit Einzelne Befehle sind meist kompatibler als eine zusammengefasste VLAN-Liste. Unterstützt die lokale Hilfe Listen, kann alternativ beispielsweise vlan 10,110,120,130 verwendet werden. Namen werden anschließend separat gesetzt. 5.3 VLANs kontrollieren show vlan brief Alle angelegten VLAN-IDs sollten als statische VLANs erscheinen. 6. Access-Port konfigurieren Ein Access-Port ist für ein normales Endgerät gedacht. Eingehende ungetaggte Frames werden dem konfigurierten VLAN zugeordnet; ausgehende Frames verlassen den Port ungetaggt. 6.1 Einzelnen Port auf Access VLAN 110 setzen configure interface 0/5 switchport mode access switchport access vlan 110 exit exit 6.2 Optional eine Beschreibung setzen Wenn die lokale CLI den Befehl anbietet: configure interface 0/5 description Client-Arbeitsplatz exit exit 6.3 Mehrere Access-Ports Die sicherste universelle Methode ist, die Portkonfiguration pro Interface zu wiederholen. Manche Firmwarestände unterstützen Interface-Bereiche, deren Syntax jedoch abweicht. Vor Verwendung eines Bereichs immer interface ? prüfen. configure interface 0/5 switchport mode access switchport access vlan 110 exit interface 0/6 switchport mode access switchport access vlan 110 exit interface 0/7 switchport mode access switchport access vlan 110 exit exit Endgerätetest Ein nicht VLAN-fähiger Client an diesem Port sollte ohne eigene VLAN-Konfiguration eine Adresse aus dem Netz von VLAN 110 erhalten. Bekommt er keine Adresse, fehlen meist DHCP, Gateway-Konfiguration oder ein VLAN auf einem vorgelagerten Trunk. 7. Trunk-Port konfigurieren Ein Trunk verbindet VLAN-fähige Geräte, zum Beispiel einen Router, einen weiteren Managed Switch, einen Hypervisor oder einen Access Point. Beide Seiten des Links müssen dieselbe VLAN-Logik verwenden. 7.1 Trunk mit Native VLAN und mehreren erlaubten VLANs configure interface 0/48 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,120,130 exit exit In diesem Beispiel läuft VLAN 10 als Native VLAN ungetaggt. VLAN 110, 120 und 130 werden getaggt übertragen. Einige Implementierungen zeigen das Native VLAN zusätzlich in der Allowed-Liste, andere behandeln es getrennt. Entscheidend ist die Ausgabe der lokalen Prüfkommandos und eine identische Konfiguration am Gegenport. 7.2 VLAN zu einem bestehenden Trunk hinzufügen configure interface 0/48 switchport trunk allowed vlan add 140 exit exit 7.3 VLAN von einem Trunk entfernen configure interface 0/48 switchport trunk allowed vlan remove 140 exit exit 7.4 Allowed-Liste vollständig ersetzen configure interface 0/48 switchport trunk allowed vlan 10,110,120,130 exit exit add und vollständige Liste nicht verwechseln switchport trunk allowed vlan add ... ergänzt die vorhandene Liste. Der Befehl ohne add kann die bisherige Liste ersetzen. Vorher show interfaces switchport trunk prüfen, sonst verschwinden VLANs mit beeindruckender Effizienz. 8. Typische Anschlussszenarien 8.1 Arbeitsplatz, Drucker, Kamera oder Server Das Endgerät versteht keine VLAN-Tags und gehört genau einem VLAN: configure interface 0/5 switchport mode access switchport access vlan 110 exit exit 8.2 Access Point mit Management- und SSID-VLANs Das Management des Access Points läuft ungetaggt in VLAN 10. Zwei SSIDs verwenden VLAN 110 und VLAN 130 getaggt: configure interface 0/24 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,130 exit exit Access-Point-Falle Das VLAN einer getaggten SSID sollte am direkten AP-Uplink nicht gleichzeitig als Native VLAN konfiguriert werden. Außerdem muss jedes SSID-VLAN auf allen Trunks zwischen AP und Gateway erlaubt sein. 8.3 Uplink zu einem Router oder einer Firewall configure interface 0/48 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,120,130 exit exit Auf dem Router beziehungsweise der Firewall werden dazu passende VLAN-Interfaces benötigt, beispielsweise: VLAN Routerfunktion 10 Management-Gateway und optional DHCP 110 Client-Gateway, DHCP und Firewallregeln 120 Voice-Gateway, DHCP-Optionen und QoS nach Bedarf 130 Gast-Gateway, DHCP und restriktive Firewallregeln 8.4 Uplink zwischen zwei Switches Beide Enden müssen dieselbe Native-VLAN- und Allowed-VLAN-Konfiguration besitzen: configure interface 0/48 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,120,130 exit exit Native-VLAN-Mismatch Wenn eine Seite VLAN 10 ungetaggt erwartet und die andere Seite ungetaggte Frames einem anderen VLAN zuordnet, entstehen schwer erkennbare Verbindungs- und Sicherheitsprobleme. Native VLANs müssen an beiden Enden übereinstimmen. 8.5 Hypervisor oder VLAN-fähiger Server Ein Hypervisor kann mehrere virtuelle Netze über einen Trunk empfangen. Das Management-VLAN kann nativ oder ebenfalls getaggt sein, abhängig von der Serverkonfiguration. Die Switch- und Hostkonfiguration müssen exakt zusammenpassen. configure interface 0/20 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,120,130 exit exit 9. Konfiguration prüfen 9.1 VLAN-Inventar show vlan brief 9.2 Access-Port prüfen show interfaces switchport access 0/5 show vlan port 0/5 show running-config interface 0/5 9.3 Trunk-Port prüfen show interfaces switchport trunk 0/48 show vlan port 0/48 show running-config interface 0/48 9.4 Linkstatus kontrollieren show interfaces status all 9.5 Praktische Funktionstests Endgerät am Access-Port anschließen. Prüfen, ob es eine IP-Adresse aus dem vorgesehenen VLAN erhält. Gateway des VLANs anpingen. DNS und erforderliche Dienste testen. Bei Trunks jedes VLAN einzeln über ein geeignetes Testgerät oder eine VLAN-fähige Schnittstelle prüfen. Firewallregeln zwischen VLANs testen, nicht nur die reine Erreichbarkeit. Erfolgskriterien Der Access-Client erhält das richtige Subnetz, der Trunk transportiert nur die vorgesehenen VLANs, das Management bleibt erreichbar und unerwünschte Inter-VLAN-Kommunikation wird durch Router oder Firewall blockiert. 10. Änderungen speichern 10.1 EdgeSwitch-/UISP-CLI Wenn die lokale Hilfe den Befehl ausweist, kann die Running-Config in den Startup-Speicher geschrieben werden: write memory Alternativ auf entsprechenden EdgeSwitch-Systemen: copy system:running-config nvram:startup-config 10.2 UniFi-USW-Geräte Keine universelle SSH-Persistenz Bei UniFi-USW-Modellen ist die lokale FastPath-Konfiguration je nach Firmware möglicherweise nur laufzeitwirksam, wird bei einem Neustart verworfen oder durch UniFi Network überschrieben. Ein hersteller- und firmwareübergreifend sicherer SSH-Befehl zum dauerhaften Speichern existiert für diese Produktgruppe nicht. Darum gilt: write memory ? beziehungsweise copy ? zuerst prüfen. Keine undokumentierten Flash-, cfgmtd- oder Dateisystembefehle aus fremden Anleitungen übernehmen. Nach einem geplanten Neustart alle VLANs und Ports erneut kontrollieren. Bei controllerverwalteten UniFi-Switches die dauerhafte Konfiguration in UniFi Network nachbauen. 11. Rückbau und Notfallplan 11.1 Access-Port zurück auf VLAN 1 configure interface 0/5 switchport mode access switchport access vlan 1 exit exit 11.2 Tagged VLAN aus einem Trunk entfernen configure interface 0/48 switchport trunk allowed vlan remove 130 exit exit 11.3 Trunk-Liste auf einen bekannten Stand setzen configure interface 0/48 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,120 exit exit 11.4 Management verloren Lokalen Konsolen- oder Ersatzport verwenden. Portplan und zuletzt geänderten Uplink kontrollieren. Native VLAN beider Linkseiten vergleichen. Prüfen, ob das Management-VLAN auf jedem vorgelagerten Trunk erlaubt ist. Switch-IP, Gateway und DHCP beziehungsweise statische IP-Konfiguration kontrollieren. Erst als letzte Maßnahme einen Factory Reset erwägen. 12. Häufige Fehler Symptom Wahrscheinliche Ursache Prüfung Access-Client erhält keine IP-Adresse VLAN fehlt auf Uplink, DHCP fehlt oder Access-VLAN ist falsch show vlan brief , Access-Port und alle Trunks bis zum Gateway prüfen Ein VLAN funktioniert, andere nicht Allowed-VLAN-Liste auf einem Trunk ist unvollständig Jeden Port entlang des Pfades prüfen Switch nach Änderung nicht mehr erreichbar Management-VLAN oder Native VLAN falsch, Gateway/IP nicht passend Konsole oder unveränderten Port verwenden AP ist erreichbar, WLAN-Clients bekommen keine Adresse SSID-VLAN nicht getaggt erlaubt oder fälschlich als Native VLAN gesetzt AP-Uplink und alle vorgelagerten Trunks prüfen Änderungen verschwinden nach Neustart Running-Config nicht gespeichert oder UniFi hat neu provisioniert Startup-/Persistenzmethode des konkreten Modells prüfen Unerwartete Kommunikation zwischen VLANs Router-/Firewallregeln erlauben Inter-VLAN-Verkehr Routing- und Firewallregeln prüfen; VLAN allein ist keine Firewall Nur ungetaggter Verkehr funktioniert Gegenstelle ist nicht VLAN-fähig oder Tags stimmen nicht überein VLAN-Konfiguration auf beiden Linkseiten vergleichen Broadcast-Sturm oder instabiles Netz Switching-Schleife oder falscher redundanter Link STP/RSTP aktiv lassen und Topologie kontrollieren 13. Entsprechung in UniFi Network In aktuellen UniFi-Network-Oberflächen wird dieselbe Logik mit den Begriffen Native VLAN / Network und Tagged VLAN Management abgebildet: SSH-/Switchbegriff UniFi-Network-Einstellung Access-Port, VLAN 110 Native VLAN / Network: VLAN 110; Tagged VLAN Management: Block All Trunk mit allen VLANs Native VLAN auswählen; Tagged VLAN Management: Allow All Trunk mit ausgewählten VLANs Native VLAN auswählen; Tagged VLAN Management: Custom und gewünschte VLANs freigeben switchport trunk native vlan 10 Native VLAN / Network: VLAN 10 switchport trunk allowed vlan ... Tagged VLAN Management: Custom 14. Kurzreferenz VLANs anlegen vlan database vlan 110 vlan name 110 Clients vlan 130 vlan name 130 Guest exit Access-Port configure interface 0/5 switchport mode access switchport access vlan 110 exit exit Trunk-Port configure interface 0/48 switchport mode trunk switchport trunk native vlan 10 switchport trunk allowed vlan 10,110,120,130 exit exit VLAN ergänzen oder entfernen configure interface 0/48 switchport trunk allowed vlan add 140 switchport trunk allowed vlan remove 130 exit exit Prüfen show vlan brief show interfaces switchport access 0/5 show interfaces switchport trunk 0/48 show vlan port all show running-config Speichern, nur wenn unterstützt write memory 15. Quellen und weiterführende Dokumentation Ubiquiti Help Center: Switch Port VLAN Assignment (Trunk & Access Ports) Ubiquiti Help Center: Creating Virtual Networks (VLANs) Ubiquiti Help Center: Virtual Network (VLAN) Troubleshooting Ubiquiti Help Center: UniFi Switch Settings UISP Help Center: EdgeSwitch CLI Reference Guide Diese Anleitung beschreibt allgemeine Netzwerkkonzepte und eine CLI-Familie. Vor produktiven Änderungen immer Modell, Firmware, lokale CLI-Hilfe, Sicherungsweg und Wiederherstellungsplan prüfen.