Aller au contenu principal

Enrôler en ligne de commande

Ce que fait la commande​

La commande baastide agent enroll échange un jeton d'enrôlement contre l'identité durable de la machine. Elle écrit cette identité dans un fichier privé. L'agent se sert ensuite de ce fichier pour chaque connexion au serveur. Il ne se sert plus du jeton.

La commande d'installation du portail fait déjà cet échange. Vous lancez l'enrôlement vous-même dans trois cas :

  • La machine a perdu son accès, et vous la rattachez avec un jeton de rattachement.
  • Vous déplacez la machine vers une autre instance BaaStide.
  • Vous ne voulez pas écrire le jeton dans une ligne de commande. Vous le donnez alors dans un fichier, sur l'entrée standard ou dans une variable d'environnement.

La commande écrit une seule ligne quand elle réussit : Enrolled as agent <identifiant>. Identity written to <fichier>.

L'identité va dans le fichier du système :

SystèmeFichier de l'identitéQui le lit
Linux/etc/baastide/agent.conf, droits 0600root seul
Windows%ProgramData%\BaaStide\agent.confSYSTEM et les administrateurs locaux seuls

Quand votre MSP a changé les noms de l'agent, le nom du programme et celui des dossiers suivent ce profil.

Prérequis​

Donner le jeton à la commande​

La commande lit le jeton dans une seule source. Choisissez-en une :

SourceOptionQuand l'utiliser
Un fichier--token-file <fichier>Une machine à la main, ou un script qui écrit un fichier privé.
L'entrée standard--token -Un script qui tient le jeton en mémoire, sans fichier.
Une variable d'environnementBAASTIDE_ENROLL_TOKEN=<jeton>Un outil de déploiement qui passe des variables.

L'option --token <jeton> fonctionne encore, mais elle montre le jeton dans la liste des processus et dans l'historique du shell. La commande écrit alors un avertissement. Ne l'utilisez pas.

La commande retire les espaces de début et de fin du jeton. Un jeton vide ou mal formé arrête la commande. Un jeton valide a 43 caractères, pris dans A-Z, a-z, 0-9, - et _.

Enrôler une machine Linux​

  1. Créez le jeton dans le portail. Copiez la valeur Jeton d'enrôlement, pour une installation manuelle.

  2. Ouvrez une session sur la machine.

  3. Devenez root. Par exemple, lancez sudo -i.

  4. Créez un fichier privé pour le jeton :

    umask 077
    cat > /root/baastide-token

  5. Collez le jeton. Appuyez sur Entrée, puis sur Ctrl+D.

  6. Lancez l'enrôlement :

    baastide agent enroll --token-file /root/baastide-token

  7. Lisez la réponse. Elle doit commencer par Enrolled as agent.

  8. Supprimez le fichier du jeton : rm -f /root/baastide-token.

  9. Démarrez le service : systemctl enable --now baastide.service.

L'étape 9 ne sert que pour un premier enrôlement. Un remplacement d'identité redémarre le service tout seul. Voir « Remplacer l'identité d'une machine » plus bas.

Enrôler une machine Windows​

  1. Créez le jeton dans le portail. Copiez la valeur Jeton d'enrôlement, pour une installation manuelle.

  2. Ouvrez une session sur la machine, avec un compte administrateur local.

  3. Ouvrez PowerShell avec Exécuter en tant qu'administrateur.

  4. Mettez le jeton dans la variable d'environnement de la session :

    $env:BAASTIDE_ENROLL_TOKEN = '<jeton>'

  5. Lancez l'enrôlement :

    & "$env:ProgramFiles\BaaStide\baastide.exe" agent enroll

  6. Lisez la réponse. Elle doit commencer par Enrolled as agent.

  7. Retirez la variable de la session :

    Remove-Item Env:BAASTIDE_ENROLL_TOKEN

  8. Démarrez le service : Start-Service BaaStide.

La commande s'arrête tout de suite dans un PowerShell qui n'est pas élevé. Elle écrit run as administrator (elevated PowerShell or command prompt).

Lire le jeton sur l'entrée standard​

Cette forme ne laisse le jeton ni dans un fichier, ni dans la liste des processus. Utilisez-la dans un script.

  1. Préparez la source du jeton. Par exemple un fichier privé, ou la sortie de votre coffre de secrets.

  2. Envoyez le jeton sur l'entrée standard de la commande.

    Sur Linux, en root :

    baastide agent enroll --token - < /root/baastide-token

    Sur Windows, dans un PowerShell administrateur :

    Get-Content C:\baastide-token | & "$env:ProgramFiles\BaaStide\baastide.exe" agent enroll --token -

  3. Lisez la réponse. Elle doit commencer par Enrolled as agent.

  4. Supprimez le fichier du jeton, si votre script en a créé un.

Avec une entrée standard vide, la commande s'arrête et écrit the enrollment token from stdin is empty.

Enrôler sur une instance on-prem​

Sans l'option --server, l'agent s'enrôle dans le service BaaStide en ligne. Pour une instance installée chez vous, donnez l'adresse de cette instance.

  1. Prenez l'adresse de l'instance dans la commande d'installation que le portail affiche.

  2. Lancez l'enrôlement avec --server. Sur Linux, en root :

    baastide agent enroll --token-file /root/baastide-token --server 'https://backup.exemple.fr'

  3. Lisez la réponse. Elle doit commencer par Enrolled as agent.

Donnez l'adresse racine de l'instance, par exemple https://backup.exemple.fr, et non https://backup.exemple.fr/api. C'est la même valeur que pour la commande d'installation. L'adresse doit commencer par https://, sans identifiant et sans paramètre.

Un jeton n'existe que sur l'instance qui l'a créé. Un jeton d'une instance on-prem envoyé au service en ligne est refusé. Le message nomme alors le serveur contacté et demande l'option --server.

Le premier contact avec une instance on-prem est protégé par TLS seul. Vérifiez l'adresse et le réseau avant de lancer la commande. Le serveur donne ensuite les empreintes de son autorité de certification. La commande les écrit dans le fichier d'identité, et l'agent les vérifie à chaque connexion suivante.

Remplacer l'identité d'une machine​

La commande refuse d'écrire sur une identité existante. L'option --force la remplace. Elle sert pour un rattachement après une révocation, et pour un déplacement vers une autre instance.

  1. Créez le jeton. Pour un rattachement, prenez le jeton du bloc Accès révoqué de la page de l'endpoint. Pour une autre instance, créez un jeton d'enrôlement sur cette instance.

  2. Ouvrez une session sur la machine, en root ou en administrateur.

  3. Lancez l'enrôlement avec --force. Sur Linux :

    baastide agent enroll --token-file /root/baastide-token --force

  4. Lisez la réponse. Elle doit commencer par Enrolled as agent.

La commande écrit la nouvelle identité, puis elle redémarre le service : l'unité baastide.service sur Linux, le service BaaStide sur Windows. L'agent se reconnecte avec sa nouvelle identité.

Sans --force, la commande s'arrête et écrit identity already exists; use --force to enroll this machine again.

L'option --no-restart laisse le service en place. Utilisez-la seulement quand vous pilotez le service vous-même. Redémarrez-le ensuite.

Limites et précautions​

  • Un jeton d'enrôlement est un secret. Ne l'écrivez pas dans un ticket, un message, un dépôt de code ou un script partagé.
  • Un jeton d'enrôlement de machine sert une seule fois, et il expire au bout de 7 jours. Un jeton de déploiement enrôle plusieurs machines, dans la limite réglée sur le jeton.
  • --token et --token-file ensemble arrêtent la commande. La variable d'environnement sert seulement quand aucune des deux options n'est donnée.
  • Un refus du serveur n'est jamais réessayé. La commande s'arrête et écrit la cause : jeton inconnu, expiré, déjà utilisé ou révoqué ; machine déjà enrôlée pour ce client ; jeton de déploiement au bout de sa limite ; adresse réseau de la machine non autorisée par le jeton.
  • L'agent envoie l'identifiant de la machine. Le serveur refuse une machine déjà enrôlée pour le même client. Une machine clonée garde l'identifiant de son modèle : donnez-lui un nouvel identifiant avant l'enrôlement. Voir Avant d'installer.
  • Quand la machine n'a aucun identifiant, l'agent s'enrôle avec un avertissement. Le serveur ne détecte alors pas un clone.
  • Un premier enrôlement ne démarre pas le service. Démarrez-le vous-même.
  • L'enrôlement suit le proxy HTTPS de son environnement, comme le reste de l'agent.
  • Le fichier d'identité est un secret. Ne le copiez pas d'une machine à une autre : chaque machine reçoit sa propre identité à son enrôlement.
  • Un nouvel enrôlement garde les réglages locaux que root a posés dans le fichier d'identité.
  • L'option --config écrit l'identité dans un autre fichier. Le service lit toujours le fichier par défaut. Ne changez ce chemin que pour un essai.
  • Sur Linux, la commande a besoin de root pour écrire dans /etc/baastide. Sans root, l'écriture du fichier échoue.

Référence​