Unter Linux installieren

Das Skript lädt die CLI für Ihre Architektur herunter, installiert sie als /usr/bin/sxaccess, registriert dann den Agenten als Systemdienst und startet ihn, so wie es sudo sxaccess agent install und sudo sxaccess agent start täten. Arbeiten Sie nicht als root, fragt es nach Ihrem Passwort. Führen Sie es deshalb für sich allein aus und warten Sie, bis es fertig ist.

Verbinden Sie danach das Gerät. sxaccess start öffnet einen Browser für die Anmeldung oder gibt den Anmeldelink aus, wenn sich kein Browser öffnen lässt. Ein Server registriert sich stattdessen mit einem Schlüssel, siehe Server ohne Bildschirm.

Er läuft unter Linux auf amd64, arm64, 386 und 32-Bit-ARM und braucht Root-Rechte: Führen Sie ihn als root aus, sonst nutzt er sudo oder doas und fragt nach Ihrem Passwort. NixOS lehnt er ab. Er installiert nicht über apt, dnf, yum oder pacman, denn es gibt keine SXAccess-Paketquelle: Er legt die eine Binärdatei an ihren Platz und registriert den Dienst.

Ein erneuter Aufruf ist unbedenklich. Findet er auf der Maschine bereits SXAccess vor, meldet er das und ersetzt die installierte Version an Ort und Stelle; Sie aktualisieren also, indem Sie ihn erneut ausführen. Führt der registrierte Dienst bereits diese Binärdatei aus, startet das Skript ihn neu, andernfalls registriert es ihn erneut.

Das Skript kennt genau eine Option. Bei jedem anderen Argument bricht es mit einem Fehler ab.

Das Skript registriert den Agenten bei dem Init-System, das die Maschine verwendet (systemd, SysV-Init, upstart oder OpenRC), sodass er beim Booten startet. Die agent-Befehle verwalten ihn auf allen diesen Systemen gleich; außer agent info brauchen sie Root-Rechte. agent info meldet Agent service: Running, solange der Agent läuft.

Der Agent protokolliert nach /var/log/sxaccess/client.log, nicht ins Journal; journalctl zeigt daher wenig. Um dem Dienst eine Variable mitzugeben, die er auswertet, verwenden Sie sudo sxaccess agent reconfigure --service-env KEY=VALUE. Der Befehl startet einen laufenden Agenten von selbst neu, und jeder Aufruf ersetzt die gesamte Umgebung des Dienstes; siehe Umgebungsvariablen.

sxaccess start und sxaccess stop verbinden und trennen das Gerät, ohne den Dienst anzufassen.

Auf einem Server gibt es keinen Browser, registrieren Sie ihn also mit einem Registrierungsschlüssel. Ein mit Schlüssel registriertes Gerät hat keinen Eigentümer, und seine Sitzung läuft nie ab; genau das braucht ein Server. Ein Gerät, das über eine Anmeldung registriert wurde, gehört dem jeweiligen Mitglied und muss sich erneut anmelden, wenn seine Sitzung abläuft.

Für einen einmaligen Aufruf übergeben Sie den Schlüssel mit --enrollment-key (-k). Kommt er aus einem Secret-Store, verweisen Sie stattdessen mit --enrollment-key-file auf eine Datei: So taucht er weder in ps noch in der Shell-Historie auf. Der Befehl sxaccess liest die Datei selbst; das Konto, das ihn ausführt, muss sie also lesen können. In einer Pipeline setzen Sie SX_ENROLLMENT_KEY; jedes Flag lässt sich auch als SX_<FLAG> setzen. Ist das Gerät bereits verbunden, meldet start This device is already connected und verwendet den Schlüssel nicht.

In einem CI-Job, der den Schlüssel als geheime Variable SX_ENROLLMENT_KEY bereitstellt, lassen Sie den Schlüssel auf der Kommandozeile weg:

Betreiben Sie den Agenten im Container mit dem Image und dem Befehl, die das Dashboard unter Add device → Docker anzeigt. Wenn Sie diesen Befehl für Compose, Kubernetes oder Podman anpassen, behalten Sie bei, was der Agent braucht:

• die Capabilities NET_ADMIN und NET_RAW, jede als eigenes Flag: --cap-add NET_ADMIN --cap-add NET_RAW. --cap-add BPF ist optional: Damit kann der Agent Hilfsfunktionen im Kernel nutzen, die er sonst durch Varianten im Userspace ersetzt;
• den Registrierungsschlüssel und den Gerätenamen als SX_ENROLLMENT_KEY und SX_HOSTNAME. Der Container liest jedes Flag aus seiner Variablen SX_<FLAG>;
• ein persistentes Volume für /var/lib/sxaccess, damit der Container seine Identität und seine Overlay-Adresse über Neustarts hinweg behält. Ohne das Volume registriert jeder Neustart ein neues Gerät.

Der Container startet den Agenten, verbindet sich mit diesen Einstellungen und schreibt das Log des Agenten in die Ausgabe des Containers, die docker logs anzeigt. Der Befehl aus Add device nennt den Container sxaccess; unter diesem Namen prüfen ihn die Befehle unten. Für Cluster und Pipelines siehe Kubernetes und CI.

Der Installer erkennt Synology: Er installiert nach /usr/local/bin, lädt das Modul tun und legt /dev/net/tun an, falls es fehlt. Jede andere Appliance mit Linux auf einer unterstützten Architektur wird wie ein Server installiert. Fügen Sie sie einem Netzwerk als Routing-Gerät hinzu, dann werden die Ressourcen dahinter erreichbar, ohne dass auf ihnen etwas installiert werden muss.

Die Identität einer Maschine ist ihr privater Schlüssel, gespeichert in /var/lib/sxaccess/default.json. Setzen Sie den Agenten zurück, wenn diese Identität nicht weiterverwendet werden soll: eine VM, die nach der Registrierung geklont wurde, eine Maschine, die an jemand anderen geht, oder ein Zustand, den ein erneutes sxaccess start nicht mehr in Ordnung bringt. Für eine erneute Anmeldung ist das nicht nötig: sxaccess start erneuert eine abgelaufene Sitzung.

Die Maschine erscheint danach als neues Gerät, mit neuem Schlüssel und neuer Overlay-Adresse. Sauber neu beginnen beschreibt dieselben Schritte für Linux und macOS. Trennen Sie zuerst die Verbindung, machen Sie die vom Agenten aufgezeichneten DNS- und Routenänderungen rückgängig und stoppen Sie den Dienst:

Löschen Sie jetzt das Gerät im Dashboard unter Devices. Das widerruft den alten Schlüssel und gibt den DNS-Namen der Maschine frei: Solange der alte Eintrag besteht, erhält ein neues Gerät diesen Namen mit zwei angehängten Zahlen.

Löschen Sie dann den Zustand des Agenten, den dieser beim Start neu anlegt, und ~/.config/sxaccess, wo verzeichnet ist, welche Identität die CLI verwendet. Starten Sie den Dienst und registrieren Sie die Maschine erneut. Auf einem Server lautet der letzte Befehl stattdessen sxaccess start --enrollment-key-file <datei>, wie unter Server ohne Bildschirm.

Unter Linux entfernen Sie Dienst, Binärdatei und Daten selbst, in dieser Reihenfolge. Stoppen Sie den Agenten, bevor Sie den Dienst entfernen: sudo sxaccess agent remove meldet ihn ab, stoppt aber keinen laufenden Agenten.

Löschen Sie das Gerät anschließend unter Devices im Dashboard, damit sein Schlüssel widerrufen wird. Auf Synology liegt die Binärdatei stattdessen unter /usr/local/bin/sxaccess.