Commands

cli

cli öffnet die eigentliche Switch-CLI, also die FastPath-/Switching-Ebene.

Dort arbeitest du mit Dingen wie:

show vlan
show running-config
configure
interface 0/1
switchport mode access
vlan database
write memory

Das ist die Cisco-ähnliche Oberfläche für:

• VLANs
• Ports
• Trunks
• Layer-2/teilweise Layer-3
• laufende Switch-Konfiguration

Das Problem: Diese CLI verwaltet hauptsächlich den laufenden FastPath-Zustand. write memory meldet zwar Erfolg, aber die UniFi-Firmware baut FastPath beim Start wieder aus /tmp/system.cfg beziehungsweise der von ubntconf erzeugten Startup-Konfiguration auf. Deshalb verschwinden die Änderungen nach einem Reboot.

mca-cli-op

mca-cli-op gehört zur UniFi-Management-Ebene.

Auf deinem Switch ist es nur ein Symlink:

/usr/bin/mca-cli-op -> mcad

Es startet also das Programm mcad in einem speziellen Betriebsmodus.

mcad kümmert sich um Dinge wie:

• Adoption
• Controller-Kommunikation
• Inform-Nachrichten
• Provisionierung
• Managementstatus
• Werksreset
• Speichern und Laden von UniFi-Konfiguration
• mgmt.is_default
• mgmt.is_setup_completed

Mit Argumenten wird es normalerweise als interner Einzelbefehl verwendet, zum Beispiel:

mca-cli-op inform
mca-cli-op set-inform http://controller:8080/inform
mca-cli-op set-default

Der Firmware-Wrapper ruft solche Befehle selbst auf. set-inform wird beispielsweise direkt an mca-cli-op weitergereicht, während set-default einen Werksreset einleitet.

Ohne Argument:

mca-cli-op

öffnet es die interaktive Management-CLI:

UniFi#

Das ist keine Linux-Shell und auch nicht dieselbe CLI wie cli. Deshalb kennt sie kein echo, awk, find oder Shell-Pipes.

Vereinfacht dargestellt

SSH-Shell
│
├── cli
│   └── FastPath-Switch-CLI
│       ├── VLANs
│       ├── Ports
│       ├── Trunks
│       └── running-config
│
└── mca-cli-op / mcad
    └── UniFi-Management-Stack
        ├── Adoption
        ├── Provisionierung
        ├── Controller/Inform
        ├── mgmt-Konfiguration
        └── Default-/Setup-Status

swctrl

swctrl ist eine interne UniFi-Switch-Control-Utility. Auf dem getesteten USW-Pro-48-US.7.5.6 meldet sie sich als Version 0.9. Sie liest hardwarenahe Switch-Zustände aus und enthält außerdem einige direkt verändernde Funktionen.

Sie ist weder die Cisco-ähnliche cli noch die UniFi-Management-CLI mca-cli-op. swctrl arbeitet näher an der laufenden Switch- und Hardware-Ebene. Änderungen sind deshalb nicht automatisch eine dauerhaft vom Controller verwaltete Konfiguration.

Aufruf und Optionen

swctrl FUNCTION
swctrl [OPTIONS]

Auf diesem Firmware-Build werden folgende globale Optionen angezeigt:

• -h zeigt die allgemeine Hilfe.
• -v aktiviert eine ausführlichere Ausgabe, sofern die aufgerufene Funktion zusätzliche Details bereitstellt.

Die Unterbefehle sind nicht vollständig in der allgemeinen Hilfe aufgeführt. Bei vielen Funktionsgruppen zeigt ein Aufruf ohne weiteren Unterbefehl die jeweilige Syntax:

swctrl
swctrl -h
swctrl mac
swctrl mac block

Funktionsgruppen

Die Hilfe von Firmware 7.5.6 nennt diese Funktionsgruppen:

• port – Portstatus, Linkzustand, Geschwindigkeit, Zähler und modellabhängige Portoperationen.
• poe – PoE-Status und modellabhängige PoE-Steuerung. Die Funktionsgruppe kann auch auf Geräten ohne PoE im gemeinsamen Firmware-Binary vorhanden sein.
• env – Umgebungs- und Hardwarewerte, beispielsweise Temperatursensoren und vorhandene Lüfterinformationen.
• mac – gelernte MAC-/Client-Einträge sowie Block- und eine in der Hilfe genannte white-Funktionsgruppe.
• sfp – Status und Diagnosedaten vorhandener SFP-/SFP+-Module.
• led – modellabhängige LED-Funktionen.
• vlan – interne VLAN-bezogene Abfragen oder Operationen; die genaue Syntax muss mit swctrl vlan auf dem jeweiligen Build geprüft werden.
• lldp – LLDP-bezogene Status- und Nachbarinformationen.
• relay – eine auf diesem Build vorhandene, aber durch die allgemeine Hilfe nicht näher erklärte Funktionsgruppe. Bedeutung und Unterbefehle müssen mit swctrl relay geprüft werden.

Wichtig: Eine aufgelistete Funktionsgruppe bedeutet nicht automatisch, dass die Hardware sie unterstützt oder dass jeder Unterbefehl auf jedem Switch identisch ist. swctrl ist stark firmware- und modellabhängig.

Typische lesende Diagnosebefehle

swctrl env show
swctrl poe show
swctrl sfp show
swctrl port show
swctrl port show counters
swctrl mac show

port show, port show counters und mac show eignen sich besonders für Live-Diagnose, weil sie den aktuellen Zustand anzeigen und selbst keine Konfiguration ändern.

Hinweis zu poe

Der getestete USW-Pro-48 ist die Variante ohne PoE. Trotzdem kann swctrl poe show vorhanden sein, weil dieselbe Utility auf mehreren Switch-Modellen verwendet wird.

Eine leere Tabelle oder ein offensichtlich unsinniger Wert wie Total Power Limit(mW): -1091736708 ist kein gültiger Leistungswert und kein verlässlicher Modelltest. Solche Ausgaben müssen als nicht unterstützte, fehlerhafte oder nicht initialisierte PoE-Abfrage behandelt werden.

mac

swctrl mac bündelt die MAC-/Client-Funktionen der laufenden Switch-Ebene. Auf Firmware 7.5.6 zeigt die Hilfe folgende Bereiche:

swctrl mac show [ id PORT_ID ]
swctrl mac block
swctrl mac white

PORT_ID darf einzelne Ports, Bereiche und kombinierte Listen enthalten:

3
5-7
1,4,9-12

mac show

swctrl mac show zeigt die vom Switch erfassten MAC-/Client-Einträge über alle Ports. Mit id lässt sich die Ausgabe auf bestimmte Ports begrenzen:

swctrl mac show
swctrl mac show id 52
swctrl mac show id 5-7
swctrl mac show id 1,4,9-12

Die Ausgabe enthält auf diesem Build folgende Spalten:

• port – Port, an dem die MAC-Adresse gelernt beziehungsweise dem Client-Eintrag zugeordnet wurde.
• vlan – VLAN-ID des Eintrags.
• mac-address – erkannte MAC-Adresse.
• ip-address – zugeordnete IP-Adresse, sofern sie der Management-Software bekannt ist.
• hostname – erkannter Hostname, sofern vorhanden.
• uptime – interner Laufzeitwert des Eintrags. Die Hilfe definiert seine genaue Bedeutung nicht; er sollte nicht ungeprüft als Geräte-Uptime bezeichnet werden.
• age – interner Alterswert, wahrscheinlich seit der letzten Aktualisierung oder Aktivität. Auch diese Einheit und Semantik wird von der Hilfe nicht erklärt.
• wireless-type – optionale WLAN-/Client-Klassifizierung; bei rein kabelgebunden erkannten Einträgen bleibt das Feld häufig leer.

Da die Ausgabe zusätzlich IP-Adresse, Hostname und WLAN-Metadaten enthalten kann, ist sie mehr als eine rohe Hardware-FDB. Fehlende IP- oder Hostname-Werte bedeuten nicht, dass die MAC-Adresse ungültig ist; die Zusatzinformationen sind schlicht nicht bekannt.

Mehrere MAC-Adressen auf demselben Port sind bei einem Uplink, einem nachgeschalteten Switch, einem Access Point, einer Bridge oder einem virtualisierten Host normal. Beim USW-Pro-48 sind neben 48 RJ45-Ports vier SFP+-Ports vorhanden. Ein Eintrag auf Port 52 passt daher zum letzten SFP+-Port; die konkrete Portzuordnung sollte trotzdem mit swctrl port show geprüft werden.

mac block

mac block verwaltet auf diesem Firmware-Build eine interne Blockliste. Die knappe Unterhilfe zeigt nur show an, tatsächlich wurden aber auch add und remove erfolgreich vom Parser akzeptiert.

swctrl mac block show
swctrl mac block add 00:87:31:73:1e:e0
swctrl mac block show
swctrl mac block remove 00:87:31:73:1e:e0
swctrl mac block show

• show zeigt die aktuell eingetragenen MAC-Adressen und den zuletzt zugeordneten Port.
• add MAC fügt die angegebene MAC-Adresse zur internen Blockliste hinzu.
• remove MAC entfernt die MAC-Adresse wieder aus der Blockliste.
• lastUpdated ist ein interner Zähler beziehungsweise Zeitwert. Die Ausgabe belegt nicht, dass es sich um einen Unix-Zeitstempel oder eine bestimmte Zeiteinheit handelt.

Folgende Varianten sind auf dem getesteten Build nicht gültig:

swctrl mac block 00:87:31:73:1e:e0
swctrl mac block del 00:87:31:73:1e:e0
swctrl mac block delete 00:87:31:73:1e:e0
swctrl mac block drop 00:87:31:73:1e:e0

Ein Aufruf wie swctrl mac block add ohne MAC-Adresse kann ohne verständliche Fehlermeldung zurückkehren. Das darf nicht als Erfolg gewertet werden. Nach jeder Änderung sollte die Blockliste erneut mit swctrl mac block show geprüft werden.

Der Eintrag in der Blockliste beweist zunächst nur, dass die MAC-Adresse in der laufenden internen Liste steht. Für eine saubere Prüfung der tatsächlichen Sperrwirkung muss der Datenverkehr des betroffenen Clients getestet werden. Ebenso sollte nach einem Reboot und nach einer Controller-Provisionierung geprüft werden, ob der Eintrag erhalten bleibt.

mac white

swctrl mac white wird von der Hilfe als weitere MAC-Funktionsgruppe genannt. Im vorliegenden Test wurde sie jedoch nicht weiter aufgerufen. Deshalb lässt sich aus den vorhandenen Daten weder die genaue Syntax noch sicher ableiten, ob sie als Whitelist, Ausnahme zur Blockliste oder für einen anderen internen Zweck verwendet wird.

Für eine belastbare Dokumentation sollte zuerst nur die Hilfe abgefragt werden:

swctrl mac white

Sicherheit und Persistenz

Eine MAC-Sperre ist keine starke Zugangskontrolle. MAC-Adressen können nachgeahmt werden. Für dauerhafte Sicherheitsregeln sind controllerverwaltete Switch-ACLs, Port-Isolation oder 802.1X geeigneter als eine manuell gesetzte Laufzeitliste.

Direkte Änderungen über swctrl sollten grundsätzlich als firmwareabhängige Laufzeitoperationen behandelt werden. Sie können nach Reboot, Firmware-Update oder erneuter Provisionierung verschwinden oder überschrieben werden.

Kurzfassung

swctrl -h

# Live-Diagnose
swctrl env show
swctrl port show
swctrl port show counters
swctrl sfp show
swctrl mac show
swctrl mac show id 52

# Laufende MAC-Blockliste
swctrl mac block show
swctrl mac block add 00:87:31:73:1e:e0
swctrl mac block remove 00:87:31:73:1e:e0

Damit ist swctrl vor allem ein Werkzeug für hardwarenahe Live-Diagnose. Einige Funktionsgruppen verändern auch den laufenden Zustand, sind aber nicht mit einer dauerhaft vom UniFi-Controller verwalteten Konfiguration gleichzusetzen.