Kommandozeilen-Referenz

Die Binärdatei sxaccess ist zugleich Kommandozeilenwerkzeug und Agent, also der Hintergrunddienst, der das Gerät verbunden hält. Die meisten Befehle übergeben ihre Arbeit über einen lokalen Socket an den laufenden Agenten; er muss also installiert sein und laufen. Das Installationsskript richtet beides ein. Die CLI läuft unter Linux und macOS; unter Windows, iOS und Android gibt es keine CLI - dort nutzen Sie die App.

sxaccess help teilt die Befehle in drei Gruppen ein: Getting connected, Everyday use und Troubleshooting and support. Die drei Tabellen unten folgen dieser Einteilung. sxaccess <Befehl> --help zeigt die Optionen eines einzelnen Befehls.

start verbindet dieses Gerät und hält es verbunden. Beim ersten Mal meldet es das Gerät an, im Browser oder, auf einer Maschine ohne Browser, mit einem Registrierungsschlüssel, und das Gerät erscheint im Dashboard. Danach verbindet sich der Agent von selbst wieder, auch nach einem Neustart; meist ist das also ein einmaliger Schritt. Bei Erfolg gibt es This device is now connected aus.

Ist das Gerät bereits verbunden, gibt start This device is already connected aus und ändert nichts: Ein Registrierungsschlüssel und alle übergebenen Einstellungen werden ignoriert. Eine Ausnahme ist die Angabe einer anderen Identität mit --profile: Dann verbindet start das Gerät mit dieser Identität neu. Um eine Einstellung zu ändern, trennen Sie das Gerät und verbinden es mit der Option neu: sxaccess stop && sxaccess start --<Option>. Für --allow-server-ssh sind Root-Rechte nötig; verwenden Sie dafür den Befehl unten. Führen Sie es als eine Zeile aus: Eine Verbindung über SXAccess, etwa eine SSH-Sitzung zu dieser Maschine, bricht ab, bis start fertig ist. In einer Sitzung über sxaccess shell klappt das nicht: Beim Stoppen schließt der Agent diese Sitzung und beendet den Befehl. Nutzen Sie dafür die Konsole oder eine OpenSSH-Sitzung.

Der Agent speichert diese Einstellungen zusammen mit der verwendeten Identität; sie gelten also, bis Sie sie wieder ändern. --block-inbound=false etwa schaltet eine davon wieder ab. Auf einer Maschine, auf der Änderungen an Identitäten abgeschaltet sind, speichert der Agent keine davon, und start verbindet mit den zuvor gespeicherten Einstellungen; siehe agent weiter unten. Solange eine Organisation aktiv ist, die Sie mit sxaccess tenant switch gewählt haben, arbeitet der Agent stattdessen mit deren eigener Konfiguration; diese Einstellungen werden dann zwar gespeichert, aber nicht angewendet. Siehe Ein Gerät zwischen Organisationen verschieben.

Ist der Agent nicht installiert oder läuft er nicht, antwortet start mit cannot reach the SXAccess agent und gibt die zwei Befehle aus, die das beheben. Welcher Fall vorliegt, zeigt sxaccess agent info. Meldet der Befehl Agent service: Stopped, ist der Dienst installiert und muss nur gestartet werden. Meldet er the service is not installed, installieren Sie ihn und starten ihn dann.

--no-browser, --profile und --tenant betreffen die Anmeldung, und enroll akzeptiert sie ebenfalls. Die übrigen sind Einstellungen, die der Agent zusammen mit der Identität speichert. Zwei weitere Optionen steuern die Quantenresistenz, eine experimentelle Funktion, die nur der CLI-Agent bietet; sxaccess start --help nennt sie, und Wie der Verkehr verschlüsselt wird erklärt, was sie bewirken.

Diesen Befehl werden Sie am häufigsten verwenden. Ohne Optionen beginnt er mit einer Kopfzeile, die die Verbindungen des Geräts zum Management-Dienst und zu Discovery zusammenfasst: Connected, Partly connected (eine der beiden ist unterbrochen) oder Not connected. Discovery ist der Dienst, über den sich zwei Geräte auf einen Pfad einigen. Darunter folgen Name und Adresse dieses Geräts, wie viele Geräte verbunden sind, die genutzten gerouteten Netze und der Zustand von Service, Discovery, Relays und DNS-Servern. Ein nicht angemeldetes Gerät erhält stattdessen eine kurze Erklärung und den Befehl, der das behebt.

-d ergänzt die verwendete Identität und die Angabe, ob der Tunnel im Kernel oder im Userspace läuft. Dazu kommt je Gerät ein Block mit Path (P2P oder Relayed), Candidates, Round trip, Last handshake, Transferred und den Netzen, die es erreicht (Reaches). Wie Sie das lesen, erklärt Fehlerbehebung am Client. -d, --json, --yaml und --ipv4 schließen einander aus. --ipv4 gibt nur die Adresse dieses Geräts aus, etwa 100.72.0.33, und mit jq -c wird aus --json eine Zeile je Gerät. Die vier --filter-by-*-Optionen schränken die Geräteliste nach Namensanfang, Adresse, Zustand oder Pfad ein; jede von ihnen schaltet die Detailansicht von selbst ein, und sie schränken auch --json und --yaml ein.

Veröffentlicht Ihr Administrator Netze für dieses Gerät, also die Ressourcen eines Netzwerks oder eine Route, kann das Gerät wählen, welche davon es routet. Das ist wichtig, wenn sich ein veröffentlichter Bereich mit etwas überschneidet, das bereits in Ihrem LAN liegt: Sie können ihn auf einer Maschine weglassen, ohne die Zugriffsregeln für alle zu ändern. Das Gerät muss verbunden sein.

reach list zeigt jedes Netz unter seinem Namen im Dashboard, also unter dem, was bei einer Ressource im Feld Name und bei einer Route im Feld Network Identifier steht, jeweils mit state: Selected oder Not Selected. reach add akzeptiert diese Namen und ersetzt die aktuelle Auswahl durch sie; mit -a fügt es sie stattdessen der Auswahl hinzu. reach add all wählt jedes veröffentlichte Netz, auch später veröffentlichte. reach remove akzeptiert Namen oder all.

Eine Identität ist eine gespeicherte Anmeldung: eigener Schlüssel, eigene Einstellungen, eigene Registrierung. Mit mehreren Identitäten wechseln Sie auf demselben Gerät zwischen Konten, ohne sich jedes Mal neu anzumelden. Jede Maschine hat die eingebaute Identität default, die sich nicht entfernen lässt; jede andere gehört dem Benutzer, der sie angelegt hat. Es ist immer nur eine Identität in Gebrauch.

identity add legt eine neue, leere Identität an. identity use wechselt zu einer anderen und trennt das Gerät, falls es verbunden ist; sxaccess start meldet das Gerät dann beim ersten Mal mit ihr an und verbindet es. start --profile <Identität> erledigt beides in einem Schritt. Die verwendete Identität lässt sich nicht entfernen.

Um zwischen Organisationen zu wechseln, denen Ihr Konto angehört, verwenden Sie stattdessen die Befehle unter sxaccess tenant. Solange eine dort gewählte Organisation aktiv ist, verwendet der Agent deren Registrierung.

diagnose collect packt die Logs des Agenten, den Verbindungsstatus und Systemangaben in ein Archiv und gibt Bundle saved to: mit dessen Pfad aus. Bei Fehlern, die nur sporadisch auftreten, greifen Sie zu diagnose capture <Dauer>. Der Befehl schaltet den Agenten auf Trace-Logging und verbindet das Gerät neu, damit die Aufzeichnung mit einer frischen Verbindung beginnt. Er läuft für die angegebene Dauer, erstellt dann das Archiv und setzt die Protokollstufe zurück. Weil der Befehl neu verbindet, brechen Sitzungen über SXAccess ab; ein getrenntes Gerät wird für die Aufzeichnung verbunden und danach wieder getrennt.

Beide akzeptieren -C, --log-file-count (wie viele rotierte Logdateien aufgenommen werden, Standard 1) und -S, --system-info (Systemangaben aufnehmen, standardmäßig eingeschaltet). Fügen Sie -A hinzu, bevor Sie ein Archiv weitergeben; was ein Archiv enthält, zeigt Was in einem Bündel steckt.

diagnose verbosity <Stufe> ändert, wie viel der Agent protokolliert, bis er neu startet: panic, fatal, error, warn, info, debug, trace. Standard ist info; mit sxaccess diagnose verbosity info kehren Sie dorthin zurück. diagnose keep-map on hält die letzte Netzwerkbeschreibung, die das Gerät erhalten hat, im Speicher, damit das nächste Archiv sie enthält; capture schaltet das von selbst ein. diagnose trace hat eine eigene Seite: Nachvollziehen, warum eine Verbindung blockiert wird.

Der Agent ist der Hintergrundprozess, der das Gerät verbunden hält. Er läuft als Systemdienst, und das Installationsskript registriert und startet ihn; diese Befehle brauchen Sie also selten. install, remove, start, stop, restart und reconfigure ändern den Systemdienst und erfordern Root-Rechte; agent info meldet nur, ob er läuft (Agent service: Running). serve führt den Agenten im Vordergrund aus: Diesen Befehl rufen der Systemdienst und der Docker-Container auf; Sie starten ihn nicht von Hand.

reconfigure registriert den Dienst mit den Optionen, die Sie angeben, neu. Ein laufender Agent wird dafür gestoppt und wieder gestartet; Sie müssen danach also nichts weiter neu starten. --service-env übergibt dem Agenten Umgebungsvariablen, und jeder Aufruf ersetzt alle bisherigen: Ein zweiter Aufruf ergänzt den ersten nicht, sondern tritt an seine Stelle. Nennen Sie deshalb jede Variable, die der Agent haben soll, in einem einzigen Aufruf, durch Kommas getrennt, etwa --service-env SX_RELAY_ONLY=true,SX_DISABLE_PROFILES=true; siehe Umgebungsvariablen. -l legt die Protokollstufe des Agenten fest; ohne Angabe ist es info.

Um Änderungen an Identitäten auf einer Maschine abzuschalten, geben Sie dem Dienst wie unten gezeigt SX_DISABLE_PROFILES=true mit. Der Agent lehnt es dann ab, Identitäten anzulegen, zu entfernen oder zu wechseln. Er speichert auch die Einstellungen nicht mehr, die start übergibt; start verbindet dann mit den zuvor gespeicherten Einstellungen. Die Option --disable-profiles, die sxaccess agent --help aufführt, bewirkt das nicht, denn install und reconfigure geben sie nicht an den Dienst weiter.

Jeder Befehl akzeptiert diese Optionen, auch wenn nur einige sie nutzen. Eine passende SX_-Umgebungsvariable überschreibt jede von ihnen - siehe Umgebungsvariablen.

start akzeptiert auch Optionen, die seine Hilfe nicht anzeigt. Verwenden Sie eine davon, wenn der Support oder eine andere Seite dieser Dokumentation dazu rät. Wie die Einstellungen unter Optionen für start werden sie zusammen mit der Identität gespeichert, und ein verbundenes Gerät ignoriert sie. Trennen und verbinden Sie es daher in einer Zeile, wie unter start gezeigt.