Documentation
Enrôler sa première machine
Enrôler une machine, c’est installer le client VIGIL-MESH puis autoriser cet appareil à rejoindre votre espace de travail. VIGIL-MESH propose trois méthodes selon le type de machine : une clé pré-autorisée pour un serveur sans écran, une invitation à durée courte pour un poste piloté par une personne, ou une file d’approbation quand vous voulez valider chaque demande à la main. Dans tous les cas, la machine n’ouvre aucun port entrant.
Les trois méthodes d’enrôlement
Le choix de la méthode dépend surtout de la machine : est-elle sans écran (headless) ou pilotée par une personne ? Le tableau ci-dessous résume les trois voies. Elles aboutissent toutes au même résultat — un appareil actif dans votre workspace — mais n’offrent pas les mêmes garde-fous.
| Méthode | Quand l’utiliser | Garde-fous |
|---|---|---|
| Clé pré-autorisée | Serveurs et machines headless, déploiements automatisés, images à cloner. | Usage limité : nombre d’utilisations et durée de validité bornés, révocable à tout moment. |
| Invitation à durée courte | Poste d’une personne que vous connaissez, mise en service ponctuelle. | Lien ou code à durée de vie courte, à usage restreint, qui expire de lui-même. |
| File d’approbation | Environnements où chaque adhésion doit être validée par un administrateur. | La machine reste en attente jusqu’à approbation explicite dans la console ; refus possible. |
Enrôler pas à pas
La séquence est la même quelle que soit la méthode : on installe le client, puis on l’autorise. Le client se charge du reste — génération de l’identité, établissement des sessions sortantes, réception de l’adresse et du nom.
- 1Installer le clientInstallez le client VIGIL-MESH sur la machine à raccorder. Voir /docs/install-windows pour Windows et /docs/install-linux pour Linux (postes et serveurs).
- 2Préparer l’autorisationDepuis la console, émettez une clé pré-autorisée pour un serveur headless, générez une invitation à durée courte pour un poste, ou activez simplement la file d’approbation si vous validez à la main.
- 3Lancer l’enrôlementSur la machine, démarrez le client avec la clé ou l’invitation, ou laissez-le déposer une demande dans la file d’approbation. Le client génère alors son identité et ouvre ses connexions vers l’extérieur — aucun port entrant n’est ouvert.
- 4Confirmer côté consoleL’appareil apparaît dans l’inventaire. En file d’approbation, approuvez-le ; sinon il devient actif. Il reçoit une adresse stable et un nom MagicDNS, prêt à rejoindre vos réseaux.
Cycle de vie d’un device
Un appareil enrôlé n’est pas figé : son statut évolue au fil de sa vie dans le workspace. Ces états se lisent et se pilotent depuis la console, et ils déterminent si la machine peut communiquer sur le mesh.
- Actif : l’appareil est autorisé et participe au réseau ; il émet et reçoit du trafic selon les politiques d’accès.
- Suspendu : l’accès est mis en pause, sans supprimer l’appareil ni son identité. Utile pour une machine temporairement hors service ou en investigation ; on peut la réactiver.
- Révoqué : l’autorisation est retirée définitivement. L’appareil perd aussitôt l’accès au réseau et devrait être ré-enrôlé, avec une nouvelle identité, s’il doit revenir.
- Expiré : l’autorisation a atteint son échéance (invitation ou clé arrivée à terme). L’appareil sort du réseau tant qu’il n’est pas ré-autorisé.
Sécurité de l’enrôlement
L’enrôlement ne se limite pas à distribuer un secret. Chaque machine possède une identité cryptographique, et le plan de contrôle diffuse une vue du réseau signée, de sorte qu’un appareil ne peut pas usurper l’identité d’un autre ni forger une topologie.
- Identité Ed25519 : à l’enrôlement, la machine génère une paire de clés Ed25519. La clé publique devient son identité stable dans le workspace ; la clé privée ne quitte jamais l’appareil.
- Netmap signée : le contrôleur distribue à chaque nœud une carte du réseau (netmap) signée, décrivant les pairs autorisés et leurs adresses. Un nœud rejette ce qui n’est pas signé par le contrôleur.
- Sessions chiffrées de bout en bout : une fois enrôlées, les machines dialoguent en QUIC/TLS 1.3, en direct de pair à pair.
- Autorisations à durée et usage bornés : clés pré-autorisées et invitations expirent, ce qui limite la fenêtre d’exposition d’un secret d’enrôlement.
In English
Enrolling a machine means installing the VIGIL-MESH client, then authorising that device into your workspace. Three methods fit different cases: a pre-authorised key for headless servers, a short-lived invitation for a person’s device, or an approval queue when you want to validate each request by hand.
Pre-authorised keys and invitations are limited in use and lifetime, and every device gets its own Ed25519 identity; the controller distributes a signed netmap so no node can impersonate another. Nodes never open an inbound port.
A device’s status can be active, suspended, revoked or expired, all managed from the console — revocation takes effect immediately.