Crew-Befehle

Ein Crew besteht aus mehreren Rechnern, auf denen Collie unter einer lead ausgeführt wird. Ihr Telefon erreicht die Herd jedes Rechners über die einzelne URL des Lead-Rechners. Der Lead ist der Rechner, den Ihr Telefon erreicht, jeder andere Rechner ist ein Mitglied, und der deputy ist das eine Mitglied, das übernehmen darf.

collie join und collie leave funktionieren weiterhin. Sie sind Aliase für collie crew join und collie crew leave mit denselben Argumenten und Exit-Codes.

collie pack funktioniert ebenfalls weiterhin für jedes Verb in dieser Tabelle. Es ist ein Alias von collie crew mit denselben Argumenten und Exit-Codes. collie docs pack gibt diese Seite aus, und die /pack-Adresse der Web-App leitet auf /crew weiter. Alle drei entfallen in 2.0.0 (ADR 0038).

Die Befehle deputy, approve-promote und promote verwalten das Failover. Anweisungen zur Einrichtung und Wiederherstellung finden Sie unter docs/deployment.md → der Standby-Weg und der Ausfalltag.

Zwei Maschinen, eine Crew

Zwei Befehle fügen eine Maschine hinzu, einer für Herdr und einer für Collie; ein manueller Weg steht für Hosts bereit, die crew add nicht per SSH erreichen kann, sowie für einen Lead, der reines HTTP ausliefert.

herdr machine add --label <name> <ssh-target>   # prepare the remote host
collie crew add <ssh-host>                      # install Collie there and enroll it

herdr machine add läuft auf dem Rechner, an dem Sie sitzen. Der Befehl richtet Herdr auf dem Remote-Host ein, speichert ihn in Herdrs eigener Liste und fügt den Rechner nicht zur Crew hinzu. collie crew add läuft auf dem Lead. <ssh-target> und <ssh-host> sind derselbe Host, angegeben als user@host oder als ein Host-Alias aus Ihrer ~/.ssh/config, und <name> benennt nur Herdrs Liste.

collie crew add <ssh-host> installiert Collie über Ihr eigenes SSH auf dem Remote-Host und registriert ihn. Es erzeugt das Token lokal, richtet Collie auf dem entfernten Rechner ein und führt dort collie crew join aus. Es erfordert Vorinstalliertes Herdr auf dem Remote-Host, was herdr machine add dort bereitstellt, sodass die beiden Befehle zusammengehören. Ein Lead, der einfaches HTTP ausliefert, erfordert einen weiteren manuellen Schritt, da crew add --insecure nicht unterstützt: Führen Sie collie crew join --insecure auf dem beitretenden Rechner aus. Verwenden Sie für einen bestimmten Host entweder crew add oder den manuellen Weg, niemals beides. collie crew add ohne Ziel listet die Hosts auf, die Ihre SSH-Konfiguration und Herdr bereits kennen, zusammengeführt anhand des Hosts, zu dem jeder Name aufgelöst wird. Wählen Sie also aus dieser Liste, anstatt den Host auf eine zweite Weise einzugeben (unten).

crew add wählt die Route, die seine eigene Installationsart vorgibt. Ein Lead, der aus einem Git-Checkout läuft, wie bei der Herdr-Plugin-Installation, überträgt seinen eigenen Commit auf das Mitglied und baut ihn dort, sodass dieses Mitglied git und Bun benötigt. Ein Lead aus dem eigenständige Installation oder aus einem Paket besitzt keinen Commit; er installiert das Mitglied daher aus der Version, die er selbst ausführt, wobei Collies eigenes Installationsprogramm über dieselbe SSH-Verbindung übertragen wird, und jenes Mitglied benötigt stattdessen curl, tar und sha256sum oder shasum. --path benennt auf der ersten Route den entfernten Checkout und auf der zweiten das Installationsverzeichnis. Ein Mitglied, das bereits die andere Installationsart ausführt, wird abgelehnt statt überschrieben, und die Ablehnung nennt den einzelnen Befehl, der dies behebt. Auf dieser zweiten Route lädt das Mitglied das Release selbst von github.com herunter; ein Mitglied ohne Verbindung zu github.com benötigt daher einen Lead, der aus einem Checkout läuft.

Das Terminal-collie crew update nutzt dieselben zwei Routen und liest denselben Zustand aus, um eine zu wählen: Ein Checkout-Lead überträgt seinen eigenen Commit auf jedes Mitglied, und ein Lead aus der eigenständigen Installation oder aus einem Paket gleicht jedes Mitglied an das Release an, das er selbst ausführt. Bei einem Release-Lead wird ein aus einem Git-Checkout laufendes Mitglied übersprungen; der Befehl, der es aktualisiert, wird in dessen Zeile aufgeführt: collie update --to-tag v<version> auf dieser Maschine. Bei einem Checkout-Lead wird ein über install.sh installiertes Mitglied umgekehrt übersprungen: Es bezieht Releases, sodass die Update-Seite des Telefons es angleicht. Ein übersprungenes Mitglied bricht den Ablauf niemals ab, und die Bestätigung zählt es separat.

Der manuelle Weg umfasst vier Befehle. Verwenden Sie ihn für einen Host, den Ihr SSH nicht erreichen kann, oder für einen Lead, der reines HTTP ausliefert, und nicht wegen der Installationsart des Leads: Jede Lead-Art fügt ein Mitglied mit crew add hinzu. Der Lead ist die Instanz, die Ihr Telefon bereits erreicht, und auf der beitretenden Maschine muss Collie installiert sein und laufen.

1. 01
   Erzeugen Sie auf dem Lead das Token.

   collie crew invite        # prints the token, then the join command to run

   Das Token ist eine Zeile: <token>.<lead-fingerprint>.

1. 01
   Treten Sie auf dem beitretenden Rechner der Crew bei und fügen Sie das Token ein, wenn Sie dazu aufgefordert werden.

   collie crew join https://lead.tail1234.ts.net

   Kopieren Sie die Adresse aus der Ausgabe von invite. Es ist die Adresse Ihres eigenen Leads, nicht dieses Beispiels.

1. 01
   Starten Sie den Lead neu, damit der laufende Prozess das neue Mitglied übernimmt.

   collie restart

1. 01
   Prüfen Sie auf dem Lead, ob die Verbindung geantwortet hat.

   collie crew status        # the new member, its address, and whether the link answered

Tokens sind einmalig verwendbar, zehn Minuten lang gültig und werden einmal angezeigt. Der Lead speichert nur den Hash. Das Ausführen von invite startet den Lead-Prozess neu, damit er die eingehende Registrierung annehmen kann, und gibt den Beitrittsbefehl einschließlich des Lead-Namens aus.

Schritt 3 ist ein zweiter Neustart, und join weist beim Beenden darauf hin. invite hat den Lead neu gestartet, damit er die Registrierung annehmen konnte. join hat das neue Mitglied dann auf die Festplatte geschrieben, und der laufende Prozess leitet keinen Datenverkehr an dieses Mitglied weiter, bis er erneut neu gestartet wird.

In einem interaktiven Terminal fragt join nach dem Token. Übergeben Sie in einem Skript - und stellen Sie das Token über stdin bereit:

collie crew join https://lead.tail1234.ts.net -   # paste the token on stdin

Übergeben Sie stattdessen @<file>, um das Token von der Festplatte zu lesen. Die direkte Übergabe von Roh-Tokens als Argumente gibt eine Warnung aus, da Prozessauflistungen Argumente für alle lokalen Benutzer offenlegen (CREW_PROTOCOL.md §8.3).

Setzen Sie die Lead-Adresse auf einen beliebigen Hostnamen oder eine host:port, die von diesem Knoten aus erreichbar ist. Eine Adresse ohne Schema und Port wird zu https://<host>:8787 aufgelöst, dem Port, an den der eigene Listener von Collie bindet.

Was crew invite ausgibt, hängt davon ab, wie der Lead veröffentlicht wird. Im standardmäßigen HTTPS-Modus lauscht der Lead auf Loopback und tailscale serve veröffentlicht ihn auf Port 443. Daher gibt invite https://<full-tailnet-name> aus, was Port 443 anwählt. Wenn Sie die Eingangstür mit COLLIE_SERVE_PORT verlegt haben, gibt es <name>:<port> aus. Bei COLLIE_SERVE_MODE=http antwortet der eigene Listener des Leads auf Port 8787 über unverschlüsseltes HTTP, und invite gibt den Kurznamen aus, mit dem Port nur dann, wenn Sie ihn geändert haben. join fragt einmal nach, bevor das Token über unverschlüsseltes HTTP gesendet wird, und --insecure bestätigt dies automatisch. Eine explizite http://-Adresse erfordert weiterhin --insecure und fragt nichts ab.

crew add übergibt dem Mitglied dieselbe Eingangstür, sodass das Mitglied ebenfalls Port 443 anwählt. Ein bloßer Name würde Port 8787 bedeuten, den ein Lead hinter tailscale serve nicht für das Tailnet öffnet.

--address auf crew join ist die Adresse, unter der der Lead diese Maschine anwählt, und sie erfordert einen Port: --address <host>:8787. join lehnt eine Adresse ohne Port ab, da der Lead sonst Port 443 anwählen würde. Eine https://host:8787-Adresse wird weiterhin akzeptiert und als host:8787 gespeichert.

Die Multiplexer-Auswahl erfolgt lokal auf jedem Knoten. Konfigurieren Sie COLLIE_MUX in der eigenen .env dieses Knotens, unter ~/.config/collie/.env bei einer Binärinstallation oder im Plugin-Konfigurationsverzeichnis von Herdr bei einer Herdr-Installation. Das Crew-Protokoll, also die Leitung zwischen den Rechnern, enthält keine Multiplexer-spezifischen Felder. Beachten Sie, dass Peers in v1 nur mit Herdr getestet wurden (CREW_PROTOCOL.md §16).

crew add legt diesen Wert für ein neues Mitglied fest, da das Mitglied ihn nicht immer selbst bestimmen kann. Ein Mitglied, auf dem genau ein Multiplexer läuft, bleibt unberührt und wählt diesen beim ersten eigenen Start aus. Bei einem Mitglied, auf dem mehrere laufen, fragt der Lead bei Ihnen nach, und Ihre Antwort wird als COLLIE_MUX in der .env dieses Mitglieds gespeichert. Ein Mitglied, das bereits einen benennt, bleibt ebenfalls unberührt. Übergeben Sie --mux <name>, um die Antwort vorab festzulegen oder einen Namen zu ersetzen, den das Mitglied bereits führt. Ein Mitglied, auf dem kein Multiplexer läuft, erhält eine Warnung und keinen Eintrag, da dessen erster Start die Ausführung verweigert, bis einer aktiv ist.

Herdr-Maschinen und die Crew

Die gespeicherten Maschinen von Herdr und eine Collie-Crew sind zwei getrennte Listen; keine davon speist die andere.

Informationen zum Hinzufügen eines Rechners finden Sie unter Zwei Maschinen, eine Crew oben.

Die Maschinenliste von Herdr gehört zu Ihrem Herdr-Fenster. Herdr 0.9.0 speichert SSH-Ziele im Client und öffnet jedes davon bei jeder Verwendung über SSH. Sie erhalten Terminals auf diesen Maschinen in diesem Fenster auf dem Rechner, an dem Sie sitzen.

Eine Crew bedeutet Collie auf jedem Rechner. Der Lead erreicht jedes Mitglied über die eigene verschlüsselte Verbindung von Collie, die einmalig durch eine Installation über Ihr SSH eingerichtet wird. Eine Crew zeigt auch Terminals an und transportiert mehr als nur Terminals. Sie überträgt Uploads. Sie speichert das Journal und das Audit-Protokoll jedes Rechners auf dem Rechner, auf dem der Bereich ausgeführt wurde. Sie aktualisiert die gesamte Crew über eine einzige Bestätigung auf dem Telefon. Sie kann den Haupteingang an einen deputy übergeben, wenn der Lead verstummt. Sie funktioniert unter tmux und zellij genauso, die überhaupt keine Rechnerliste führen.

Drei Tatsachen halten die beiden Listen getrennt, und jede davon ist für sich genommen ein Grund.

Das Telefon speichert niemals einen SSH-Schlüssel. Ein SSH-Schlüssel bietet eine vollständige Shell auf dem Rechner, und ein Telefon geht verloren. Das Telefon speichert stattdessen einen Kopplungscode, den der Lead ausgestellt hat. Dieser öffnet die App und sonst nichts, und collie devices revoke <label> beendet diesen Code im laufenden Betrieb, ohne Neustart (Ein Gerät koppeln).

Uploads, das Journal und das Audit-Protokoll liegen auf dem Rechner, der den Bereich ausführt. Und die Crew-Verbindung, wie Collie die verschlüsselte Leitung zwischen zwei Rechnern nennt, benötigt kein SSH mehr, sobald ein Mitglied registriert ist.

Sie richten dieselbe Sache also nicht zweimal ein. Sie richten SSH einmal ein, und beide Werkzeuge nutzen es. Herdr behält seine Liste für das eigene Fenster, und Collie behält die Crew für Ihr Telefon. Das Hinzufügen einer Maschine zu Herdr fügt sie nicht zur Crew hinzu. Das Entfernen aus Herdr entfernt sie nicht aus der Crew. Ein Crew-Mitglied, auf dem tmux oder zellij läuft, erscheint niemals in der Liste von Herdr.

collie crew add ohne Ziel bietet Kandidaten aus beiden Listen an, sodass Sie einen Host nie zweimal eingeben. Es liest Host-Einträge in Ihrer ~/.ssh/config und führt herdr machine list --json aus. Es führt die beiden Listen anhand des SSH-Ziels zusammen, zu dem jeder Name aufgelöst wird. Der Befehl folgt einem Include in dieser Konfiguration eine Ebene tief und nur für Pfade unter ~/.ssh/. Es bietet keinen Alias in einer Datei an, die aus einer eingebundenen Datei stammt. Jede Zeile zeigt, woher der Name stammt: ssh config, herdr oder beide. Eine Zeile für eine Maschine, die sich bereits in dieser Crew befindet, trägt die ID dieses Mitglieds anstelle einer Nummer.

Wie eine Crew verdrahtet ist

Nur der Lead stellt einen Haupteingang bereit, und jeder andere Rechner in der Crew stellt keinen bereit.

Der Lead ist der verwaltete Haupteingang und liefert die PWA aus. Das Telefon erreicht ihn über HTTPS auf /api/* und kommuniziert mit nichts anderem. Der Lead erreicht jedes Mitglied auf /crew/v1/* über angeheftetes Mutual TLS, das das Crew-Geheimnis überträgt. Ein Mitglied ist ein vollständiges Collie ohne Haupteingang und verwaltet seine eigenen Agents, sein Journal, seine Uploads und sein Audit-Protokoll. Die Verwaltung erfolgt vollständig über das CLI, ohne Herdr-UI-Aktionen. Die Verbindung selbst ist in CREW_PROTOCOL.md spezifiziert.

Code wird über Ihr eigenes SSH auf jeden Rechner übertragen. crew add installiert ein Mitglied auf diese Weise und crew update gleicht es an. Die Crew-Verbindung überträgt Laufzeitdaten und wird niemals zu einem Verteilungskanal.

Ein deputy ist ein Peer, den die Leitung im Voraus benannt hat. Er bindet einen Standby-Zugang mit drei Routen, und dieser Zugang wird niemals veröffentlicht. Das Schweigen der Leitung aktiviert ihn, und Ihre eigenen Kopplungsanmeldedaten lösen ihn ein, sodass das Telefon den deputy erreichen kann, während die Leitung weg ist.

Mitglieder, die nicht durch install.sh installiert wurden

Eine Crew aktualisiert jedes Mitglied vom Telefon aus, mit Ausnahme der Mitglieder, deren Dateien jemand anderem gehören.

collie crew update und die 1-Tipp-Crew-Aktualisierung des Telefons stellen beide ein neues Release neben dem alten bereit und tauschen es aus. Das funktioniert bei den beiden Installationen, die das Installationsskript und Herdr durchführen, und es funktioniert nicht bei jeder Installation; daher meldet die Crew die anderen, anstatt sie fehlschlagen zu lassen.

Ein paketiertes Mitglied wartet auf seine Paketverwaltung. Wo pacman, nix oder brew die Dateien ablegen, gehören sie diesem Paketmanager, und Collie ersetzt keine Datei, die ihm nicht gehört (Eine paketierte Installation). Die Crew sendet ihr niemals ein Update, zeigt sie als "wartet auf den Paketmanager" mit dem Befehl für ihr Präfix an, sofern einer benannt werden kann, und wertet den Durchlauf ohne sie als abgeschlossen. Der Zustand gleicht sich an, wenn Sie diesen Befehl auf dieser Maschine ausführen, und die Zeile verschwindet bei der nächsten Prüfung.

Eine paketierte LEAD-Instanz gleicht ihre Mitglieder weiterhin an. Der Lead lehnt den eigenen Versionswechsel aus demselben Grund ab, und das ist die gesamte Verweigerung: Das Telefon und collie crew update gleichen jedes Mitglied an die Version an, die der Lead derzeit ausführt, und eine einzige Bestätigung deckt sie ab. Nachdem die Paketverwaltung den Lead aktualisiert hat und Sie collie restart darauf ausgeführt haben, gleicht sich nichts von selbst an; eine weitere Bestätigung auf der Update-Seite des Telefons bringt die Mitglieder auf die neue Version des Leads.

Ein Quellcode-Checkout ist ein vollwertiges Mitglied unter einem Lead, der ebenfalls einen besitzt. Ein Mitglied, das Sie selbst geklont und gebaut haben, übernimmt das Crew-Update von einem Checkout-Lead: Dieser Lead überträgt seinen Commit, baut neu und startet neu, genau wie bei sich selbst. Unter einem Lead ohne Commit überspringt collie crew update das Mitglied und benennt collie update --to-tag v<version> zur Ausführung auf jener Maschine.

Eine gemischte Crew ist also eine normale Crew. Ein Antippen aktualisiert jedes Mitglied, das die Lead-Instanz aktualisieren kann, benennt diejenigen, bei denen dies nicht möglich ist, und die Crew ist wieder auf dem gleichen Stand, sobald Sie deren Paketmanager ausgeführt haben.

Der Name der Crew

Der Name einer Crew dient nur der Anzeige, und nur die Lead-Instanz zeigt ihn an. collie crew invite --name "the shed" benennt eine Crew bei ihrer Erstellung; eine ohne --name erstellte Crew heißt "collie crew". Um ihn später zu ändern, führen Sie collie crew rename <name> auf der Lead-Instanz aus. Das Verb überschreibt den Namen in der eigenen crew-trust.json der Lead-Instanz und startet die Bridge neu, sodass collie crew status und die Crew-Seite des Telefons den neuen Namen sofort anzeigen.

An ein Mitglied wird nichts gesendet. Der Name wird einmalig übertragen, in der Antwort des Leads auf eine Registrierung, und ein Mitglied speichert ihn, ohne ihn jemals anzuzeigen. Eine Maschine, die nach dem Umbenennen beitritt, erhält den neuen Namen, und die bereits in der Crew vorhandenen Mitglieder behalten die alte Zeichenkette in einem Feld, das niemand liest. Ein Name wird getrimmt, ist höchstens 64 Zeichen lang und enthält keine Steuerzeichen. Auf einem Peer oder auf einer Maschine ohne Crew verweigert das Verb die Ausführung und gibt an, wo es ausgeführt werden muss.

Aktualisierung auf 1.9.0 von 1.7.0 oder 1.8.x

Bringen Sie jedes Mitglied auf 1.8.x, bevor Sie den Lead auf 1.9.0 aktualisieren. 1.9.0 unterstützt eine Version der Crew-Verbindung, und 1.8.0 ist der älteste Build, der sie unterstützt.

Sie müssen sich nicht merken, welche Releases das sind. Ab 1.8.0 teilt Ihnen der Update-Hinweis mit, wenn das bevorstehende Release die Crew-Verbindung ändert – auf dem Band, auf der Updates-Karte und im täglichen Push. Dort steht dasselbe: Aktualisieren Sie zuerst den Lead, die Mitglieder folgen.

1.8.0 benennt die Namen um, die ein Rechner liest. Die Leitungspfade, die beiden Umgebungsschlüssel, die drei Statusdateien und das Journal-Präfix lauten nun alle crew (ADR 0039). Die Verbindung verhält sich exakt wie zuvor, und nichts, was Sie per Skript gesteuert haben, muss am selben Tag umgestellt werden.

1.8.0 unterstützte ein 1.7.0-Mitglied für ein Release; 1.9.0 tut dies nicht. Ein 1.8.0-Lead hat auch auf die alten Pfade geantwortet, sodass ein Mitglied, das noch auf 1.7.0 war, ihm weiterhin folgte. 1.9.0 hat dies entfernt, wie in ADR 0039 angekündigt.

Ein Mitglied, das unter einem 1.9.0-Lead noch auf 1.7.0 ist, taucht zweimal auf, und keines von beiden ist stumm. Der Vorab-Check des Leads markiert die Überprüfung version rot, nennt beide Versionen sowie den auszuführenden Befehl, und dieses Rot blockiert das Crew-Update, anstatt einen Rollout zu starten, der nicht abgeschlossen werden kann. In collie crew status liest dasselbe Mitglied incompatible, mit einer Begründung, die auf „this build speaks 2“ endet.

Aktualisieren Sie dieses Mitglied von dessen eigener Maschine aus. Ein 1.9.0-Lead kann es über die Verbindung nicht mehr erreichen; führen Sie dort daher collie update aus, bringen Sie es auf 1.8.x oder neuer, und der Lead erfasst es bei der nächsten Abfrage.

Die neuen Namen

Benennen Sie die beiden Umgebungsschlüssel in Ihrer eigenen .env um, bevor Sie auf 1.9.0 umsteigen. Ein 1.9.0-Build liest den alten Schlüssel nicht und warnt nicht davor.

Bei einem Journal, das die Aktualisierung überspannt, suchen Sie mit grep nach beiden Präfixen:

journalctl --user -u collie | grep -E '\[(crew|pack)\]'

Eine vor der Aktualisierung geschriebene Zeile enthält [pack], und eine danach geschriebene Zeile enthält [crew]. Sobald die gesamte Crew auf 1.8.0 ist, filtern Sie nur noch nach [crew].