# 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.