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

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

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 <benutzer>@<switch-ip>

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 <port> 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

  1. Endgerät am Access-Port anschließen.
  2. Prüfen, ob es eine IP-Adresse aus dem vorgesehenen VLAN erhält.
  3. Gateway des VLANs anpingen.
  4. DNS und erforderliche Dienste testen.
  5. Bei Trunks jedes VLAN einzeln über ein geeignetes Testgerät oder eine VLAN-fähige Schnittstelle prüfen.
  6. 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:

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

  1. Lokalen Konsolen- oder Ersatzport verwenden.
  2. Portplan und zuletzt geänderten Uplink kontrollieren.
  3. Native VLAN beider Linkseiten vergleichen.
  4. Prüfen, ob das Management-VLAN auf jedem vorgelagerten Trunk erlaubt ist.
  5. Switch-IP, Gateway und DHCP beziehungsweise statische IP-Konfiguration kontrollieren.
  6. 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

Diese Anleitung beschreibt allgemeine Netzwerkkonzepte und eine CLI-Familie. Vor produktiven Änderungen immer Modell, Firmware, lokale CLI-Hilfe, Sicherungsweg und Wiederherstellungsplan prüfen.

Revision #1
Created 2026-07-30 19:11:25 UTC by Julian
Updated 2026-07-30 19:11:36 UTC by Julian