Commandes crew

Un crew regroupe plusieurs machines exécutant Collie sous un même lead, et votre téléphone accède à la herd de chaque machine via l'URL unique du lead. Le lead est la machine que votre téléphone joint, chaque autre machine est un membre, et le deputy est le seul membre autorisé à prendre le relais.

collie join et collie leave fonctionnent toujours. Ce sont des alias de collie crew join et collie crew leave, utilisant les mêmes arguments et codes de sortie.

collie pack fonctionne toujours aussi, pour chaque verbe de ce tableau. C'est un alias de collie crew avec les mêmes arguments et codes de sortie. collie docs pack affiche cette page, et l'adresse /pack de l'application web redirige vers /crew. Tous les trois disparaissent dans la version 2.0.0 (ADR 0038).

Les commandes deputy, approve-promote et promote gèrent le basculement. Pour les instructions de configuration et de récupération, consultez docs/deployment.md → la porte de secours et le jour de panne.

Deux machines, une crew

Deux commandes permettent d'ajouter une machine, une pour Herdr et une pour Collie, et une procédure manuelle est prévue pour les hôtes auxquels elles ne conviennent pas.

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 s'exécute sur la machine devant laquelle vous vous trouvez. Elle installe Herdr sur l'hôte distant et l'enregistre dans la propre liste de Herdr, sans ajouter la machine au crew. collie crew add s'exécute sur le lead. <ssh-target> et <ssh-host> désignent le même hôte, écrit sous la forme user@host ou d'un alias Host de votre ~/.ssh/config, et <name> sert uniquement de libellé dans la liste de Herdr.

collie crew add <ssh-host> installe Collie sur l'hôte distant via votre propre ssh et l'enrôle. La commande génère le jeton localement, provisionne Collie sur la machine distante et y exécute collie crew join. Elle nécessite Herdr préinstallé sur l'hôte distant, que herdr machine add y dépose, ces deux commandes s'utilisent donc ensemble. Un lead qui fonctionne en HTTP simple nécessite une étape manuelle supplémentaire, car crew add ne prend pas en charge --insecure : exécutez collie crew join --insecure sur la machine qui rejoint le crew. Utilisez soit crew add, soit la procédure manuelle pour un hôte donné, jamais les deux. collie crew add sans cible liste les hôtes déjà connus par votre configuration ssh et Herdr, fusionnés selon l'hôte résolu par chaque nom ; choisissez donc dans cette liste plutôt que de saisir l'hôte sous une autre forme (ci-dessous).

La procédure manuelle comporte quatre commandes. Le lead est l'instance que votre téléphone joint déjà, et la machine qui le rejoint doit avoir Collie installé et en cours d'exécution.

1. 01
   Sur le lead, générez le jeton.

   collie crew invite        # prints one line: <token>.<lead-fingerprint>

1. 01
   Sur la machine qui rejoint, intégrez le crew et collez le jeton lorsque vous y êtes invité.

   collie crew join lead

1. 01
   Sur le lead, redémarrez-le pour que le processus en cours prenne en compte le nouveau membre.

   collie restart

1. 01
   Sur le lead, vérifiez que le lien a répondu.

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

Les tokens sont à usage unique, valables dix minutes et affichés une seule fois. Le lead ne stocke que le hash. Exécuter invite redémarre le processus du lead pour qu'il puisse accepter l'enrôlement entrant, et affiche la ligne de jonction incluant le nom du lead.

L'étape 3 est un second redémarrage, et join l'indique en se terminant. invite a redémarré le lead pour qu'il accepte l'enrôlement. join a ensuite écrit le nouveau membre sur le disque, et le processus en cours d'exécution ne relaie pas le trafic vers ce membre tant qu'il n'a pas redémarré.

Dans un terminal interactif, join demande le token. Dans un script, passez - et fournissez le token sur stdin :

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

Passez plutôt @<file> pour lire le token depuis le disque. Passer des tokens bruts directement en arguments affiche un avertissement, car la liste des processus expose les arguments à tous les utilisateurs locaux (CREW_PROTOCOL.md §8.3).

Définissez l'adresse du lead sur n'importe quel nom d'hôte ou host:port joignable depuis ce nœud. Une adresse sans protocole ni port est résolue en https://<host>:8787, le port par défaut sur lequel Collie écoute. La sortie de crew invite précise le port si le lead l'a modifié. Une installation par défaut répond sur le port 8787 en HTTP brut, précédé de TLS sur le port 443 ; join peut donc ne trouver aucun TLS sur 8787. Il demande confirmation une fois avant d'envoyer le token en HTTP brut ; --insecure confirme cela automatiquement. Une adresse explicite en http:// requiert toujours --insecure et ne demande aucune confirmation.

La sélection du multiplexeur est locale à chaque nœud. Configurez COLLIE_MUX dans le .env propre à ce nœud, dans ~/.config/collie/.env pour une installation binaire ou dans le dossier de configuration des plugins de Herdr pour une installation Herdr. Le protocole crew, qui constitue la liaison réseau entre les machines, ne contient aucun champ spécifique à un multiplexeur. Notez que les pairs n'ont été testés qu'avec Herdr en v1 (CREW_PROTOCOL.md §16).

Machines Herdr et le crew

Les machines enregistrées de Herdr et un crew Collie sont deux listes distinctes, et aucune n'alimente l'autre.

Pour ajouter une machine, consultez Deux machines, une crew ci-dessus.

La liste des machines de Herdr appartient à votre fenêtre Herdr. Herdr 0.9.0 conserve les cibles SSH enregistrées dans son client et ouvre chacune d'elles via SSH chaque fois que vous l'utilisez. Vous obtenez des terminaux sur ces machines, dans cette fenêtre, sur la machine devant laquelle vous êtes assis.

Une crew correspond à Collie présent sur chaque machine. Le lead joint chaque membre via le lien chiffré propre à Collie, configuré une fois lors d'une installation passant par votre SSH. Une crew affiche aussi les terminaux, et transporte bien plus que des terminaux. Elle transfère les téléversements. Elle conserve le journal et le log d'audit de chaque machine sur celle qui a exécuté le volet. Elle met à jour toute la crew à partir d'une seule confirmation sur le téléphone. Elle peut transférer la porte d'entrée à un deputy lorsque le lead ne répond plus. Elle fonctionne à l'identique sous tmux et zellij, qui n'ont aucune liste de machines.

Trois faits séparent ces deux listes, et chacun constitue une raison en soi.

Le téléphone ne détient jamais de clé SSH. Une clé SSH offre un shell complet sur la machine, et un téléphone peut se perdre. Le téléphone conserve à la place un code d'association émis par le lead, qui ouvre l'application et rien d'autre, et collie devices revoke <label> révoque ce code à chaud, sans redémarrage (associer un appareil).

Les téléversements, le journal et le log d'audit résident sur la machine qui exécute le volet. Et le lien de crew, comme Collie appelle la ligne chiffrée entre deux machines, n'a plus besoin de SSH une fois le membre enrôlé.

Vous ne configurez donc pas la même chose deux fois. Vous configurez SSH une seule fois, et les deux outils l'utilisent. Herdr conserve sa liste pour sa propre fenêtre, et Collie conserve le crew pour votre téléphone. Ajouter une machine à Herdr ne l'ajoute pas au crew. Supprimer une machine de Herdr ne la supprime pas du crew. Un membre du crew exécutant tmux ou zellij n'apparaît jamais dans la liste de Herdr.

collie crew add sans cible propose les candidats des deux listes, pour que vous n'ayez jamais à saisir un hôte deux fois. Elle lit les entrées Host de votre ~/.ssh/config et exécute herdr machine list --json. Elle fusionne les deux listes selon la cible ssh vers laquelle chaque nom résout. La commande suit un Include dans cette configuration sur un seul niveau, et uniquement pour les chemins sous ~/.ssh/. Elle ne propose pas d'alias issu d'un fichier inclus depuis un fichier inclus. Chaque ligne indique la provenance du nom : ssh config, herdr, ou les deux. La ligne d'une machine faisant déjà partie de cette crew affiche l'identifiant de ce membre à la place d'un numéro.

Comment une crew est reliée

Seul le lead expose une porte d'entrée, et toutes les autres machines de la crew n'en exposent aucune.

Le lead est la porte d'entrée gérée, et il sert la PWA. Le téléphone le joint en HTTPS sur /api/* et ne communique avec rien d'autre. Le lead joint chaque membre sur /crew/v1/*, via un TLS mutuel épinglé transportant le secret de la crew. Un membre est un Collie complet sans porte d'entrée, et il conserve ses propres agents, son journal, ses téléversements et son log d'audit. La gestion s'effectue entièrement via la CLI, sans actions dans l'UI de Herdr. Le protocole réseau lui-même est spécifié dans CREW_PROTOCOL.md.

Le code transite par votre propre SSH vers chaque machine. crew add installe un membre de cette façon et crew update le met à niveau. Le lien de crew transporte les données d'exécution, et ne devient jamais un canal de distribution.

Un deputy est un pair désigné à l'avance par le lead. Il réserve une porte de secours avec trois routes, et cette porte n'est jamais publiée. Le silence du lead l'arme, et votre propre identifiant d'association la consomme, permettant au téléphone de joindre le deputy pendant l'absence du lead.

Membres non installés par install.sh

Une crew met à jour chaque membre depuis le téléphone, sauf ceux dont les fichiers appartiennent à un autre propriétaire.

collie crew update et la mise à jour de crew en un geste sur le téléphone préparent tous deux une nouvelle version à côté de l'ancienne avant de basculer. Cela fonctionne sur les deux types d'installation effectués par le script d'installation et Herdr, mais pas sur tous les types d'installation; la crew signale donc les autres au lieu d'échouer.

Un membre installé par paquet attend son gestionnaire de paquets. Lorsque pacman, nix ou brew placent les fichiers, ce gestionnaire en est le propriétaire, et Collie ne remplace aucun fichier qui ne lui appartient pas (une installation par paquet). La crew ne lui envoie jamais de mise à jour, l'affiche avec l'état « en attente du gestionnaire de paquets » accompagné de la commande pour son préfixe si elle est connue, et considère l'opération terminée sans lui. Il se met à niveau lorsque vous exécutez cette commande sur cette machine, et la ligne disparaît lors de la vérification suivante.

Un LEAD installé par paquet met toujours ses membres à niveau. Le lead refuse son propre déplacement pour la même raison, et le refus s'arrête là : le téléphone met toujours à niveau chaque membre vers la version actuellement exécutée par le lead, et la confirmation les prend en compte. Une fois que le gestionnaire de paquets a mis à jour le lead et que vous avez exécuté collie restart dessus, rien ne se met à niveau automatiquement; une confirmation supplémentaire sur la page Updates du téléphone aligne les membres sur la nouvelle version du lead.

Un checkout source est un membre à part entière. Un membre cloné et compilé par vos soins se met à jour via git comme n'importe quel checkout, accepte la mise à jour de crew, et n'appelle aucun commentaire particulier ici. Le lead récupère le tag, recompile et redémarre exactement comme il le fait pour lui-même.

Une crew mixte est donc une crew normale. Un seul geste met à niveau chaque membre que le lead peut mettre à jour, indique ceux qu'il ne peut pas mettre à jour, et la crew est de nouveau à niveau dès que vous avez exécuté leurs gestionnaires de paquets.

Le nom du crew

Le nom d'un crew est une donnée d'affichage, et seul le lead le montre. collie crew invite --name "the shed" nomme un crew lors de sa création, et un crew créé sans --name s'appelle « collie crew ». Pour le modifier ultérieurement, exécutez collie crew rename <name> sur le lead. Le verbe réécrit le nom dans le crew-trust.json du lead et redémarre le bridge, de sorte que collie crew status et la page crew du téléphone affichent immédiatement le nouveau nom.

Rien n'est envoyé à un membre. Le nom transite une seule fois, dans la réponse du lead à une inscription, et un membre le stocke sans jamais l'afficher. Une machine qui rejoint après le renommage reçoit le nouveau nom, et les membres déjà présents dans le crew conservent l'ancienne chaîne dans un champ que personne ne lit. Un nom est nettoyé (trimmed), comporte au maximum 64 caractères et ne contient aucun caractère de contrôle. Sur un pair, ou sur une machine n'appartenant à aucun crew, le verbe refuse de s'exécuter et indique où le lancer.

Mise à jour depuis 1.7.0

Mettez d'abord à jour le lead. Le téléphone et collie crew update suivent déjà cet ordre, et 1.8.0 ajoute une seconde raison à cela.

Vous n'avez pas besoin de retenir de quelles versions il s'agit. À partir de 1.8.0, la notification de mise à jour vous indique quand la prochaine version modifie le lien du crew, sur le bandeau, sur la carte Mises à jour et dans la notification push quotidienne, et elle répète la même consigne : mettez d'abord à jour le lead, les membres suivent.

1.8.0 renomme les identifiants qu'une machine lit. Les chemins réseau, les deux clés d'environnement, les trois fichiers d'état et le préfixe du journal utilisent désormais tous crew (ADR 0039). Le lien fonctionne exactement comme avant, et aucun de vos scripts n'a besoin d'être modifié le jour même.

Un lead 1.8.0 maintient un membre 1.7.0 synchronisé derrière lui. Le lead répond aux anciens chemins /pack/v1/* pendant une version, de sorte qu'un membre encore en 1.7.0 s'inscrit, répond au hello et s'aligne via la liaison existante. Un lead encore en 1.7.0 ne peut pas lire la ligne d'état d'un membre 1.8.0, ce qui explique pourquoi l'ordre imposait déjà de mettre le lead à jour en premier.

Un membre mis à jour en premier n'est pas bloqué. Un membre 1.8.0 appelle /crew/v1/*, bascule une fois sur /pack/v1/* face à un lead 1.7.0, et consigne une ligne de journal signalant cette opération. Les anciens chemins et ce mécanisme de secours disparaissent en 1.9.0 ; faites donc migrer l'ensemble du crew vers 1.8.0 avant cette version.

Les nouveaux noms

Renommez les deux clés d'environnement dans votre .env quand vous le souhaitez. Tant que ce n'est pas fait, Collie lit l'ancienne clé et affiche cet avertissement à chaque démarrage.

Sur un journal qui couvre la mise à jour, cherchez les deux préfixes avec grep :

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

Une ligne écrite avant la mise à jour indique [pack], et une ligne écrite après indique [crew]. Une fois que toute l'équipe est en 1.8.0, filtrez uniquement sur [crew].