Restaurer en ligne de commande sur la machine

Ce que fait la fonction

La commande baastide restore restaure les fichiers d'une machine depuis la machine elle-même. Vous la lancez sur place, en tant que root ou administrateur. Elle ne demande ni compte du portail ni clé API.

La commande ne restaure pas elle-même : elle demande au service de l'agent de le faire. Le service demande une session de lecture à la plateforme, lit le point de restauration dans le stockage, puis écrit les fichiers sous un dossier cible, avec leur arborescence d'origine. Le mot de passe du dépôt et le jeton d'accès restent dans la mémoire du service. La commande ne les reçoit jamais.

Choisissez cette restauration quand le portail ne peut pas restaurer vers la machine. Le portail propose lui-même la ligne de commande dans deux cas : l'agent de la machine cible est trop ancien, ou le client a coupé les restaurations depuis le portail sur cette machine. Il écrit alors « En ligne de commande : lancez baastide restore sur la machine. »

Pour restaurer depuis le portail, voir Restaurer des fichiers depuis le portail.

Prérequis

• Un accès root sur une machine Linux. Un PowerShell ouvert en tant qu'administrateur sur une machine Windows. Le service de l'agent n'accepte que son propre utilisateur sur Linux, et SYSTEM ou les administrateurs locaux sur Windows.
• Le service de l'agent en marche sur la machine, enrôlé, et connecté à la plateforme. Voir Enrôler en ligne de commande.
• Un agent accepté par la plateforme. Un agent sous le minimum de la plateforme est bloqué : la plateforme refuse la session. Voir Versions d'agent minimales par fonction.
• Au moins un point de restauration sur la machine. Voir Trouver le bon point de restauration.
• De la place libre sur le disque qui porte le dossier cible.

Aucun rôle du portail n'est nécessaire. La plateforme écrit quand même chaque session dans le journal d'audit. Voir Journal d'audit.

Une restauration n'a pas besoin d'une licence qui permet les sauvegardes. Seules les données d'un essai terminé sont bloquées. Voir Choisir la bonne restauration.

Appeler la commande

Sur Linux :

sudo baastide restore --list

Sur Windows, dans un PowerShell administrateur :

& "$env:ProgramFiles\BaaStide\baastide.exe" restore --list

Les exemples qui suivent utilisent la forme Linux. Sur Windows, remplacez baastide par le chemin complet de l'exécutable.

Un agent en marque blanche porte un autre nom d'exécutable et d'autres dossiers. Lisez le nom installé sur la machine. Voir Marque blanche de l'agent.

Lister les points de restauration de la machine

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

2. Lancez :

   sudo baastide restore --list

3. Lisez la sortie. C'est une ligne JSON : un tableau d'objets, du point le plus ancien au point le plus récent.

   [{"id":"4bba301e9f0c2d7a…","time":"2026-11-04T01:12:03.482461Z","hostname":"srv-fichiers","paths":["/srv/donnees"]}]

4. Repérez le point à restaurer dans la liste.

Chaque objet porte quatre champs :

Champ	Ce qu'il donne
id	L'identifiant du point de restauration, sur 64 caractères.
time	La date de la sauvegarde, relevée sur la machine.
hostname	Le nom de la machine au moment de la sauvegarde.
paths	Les chemins que la sauvegarde a lus.

Sur Linux, ajoutez | jq à la commande pour lire la sortie sur plusieurs lignes, quand jq est installé.

La liste donne tous les points du dépôt de la machine, quel que soit le type de sauvegarde : fichiers, image, bases SQL Server et machines virtuelles. Lisez paths pour reconnaître le contenu d'un point. L'assistant du portail, lui, ne montre que les points de fichiers.

Restaurer le point le plus récent

1. Choisissez un dossier cible. Voir Choisir le dossier cible.

2. Lancez :

   sudo baastide restore latest --target /var/lib/baastide/restore/test

3. Attendez la fin. La commande n'affiche pas d'avancement.

4. Lisez la dernière ligne. Après une restauration réussie, elle donne Restored snapshot <identifiant>.

5. Ouvrez le dossier cible et vérifiez les fichiers.

Le mot latest prend le point le plus récent du dépôt de la machine, quel que soit son type. Sur une machine qui porte plusieurs politiques, donnez l'identifiant du point à la place de latest.

Restaurer un point précis

1. Relevez l'identifiant du point avec --list.

2. Lancez la commande avec cet identifiant :

   sudo baastide restore 4bba301e --target /var/lib/baastide/restore/test

3. Lisez la dernière ligne, puis vérifiez les fichiers dans le dossier cible.

Vous donnez l'identifiant complet, ou son début sur 8 caractères au moins. Un début qui ne correspond à aucun point, ou à plus d'un point, est refusé. La commande le dit, et --list donne les identifiants complets.

Choisir le dossier cible

Le dossier cible obéit à quatre règles :

1. Le chemin est absolu. Un chemin relatif est refusé.
2. Le dossier peut ne pas exister encore. L'agent le crée.
3. Les fichiers arrivent sous ce dossier, avec leur arborescence d'origine. La commande ne restaure jamais un fichier à son emplacement d'origine. Pour cela, passez par le portail.
4. Sur Linux, le dossier doit être visible en dehors du service de l'agent, et accessible en écriture pour lui.

Sur Linux, le service de l'agent a son propre /tmp et son propre /var/tmp : un fichier écrit là n'est visible que par le service. N'utilisez donc pas /tmp ni /var/tmp comme dossier cible. Utilisez un dossier sous /var/lib/baastide/restore.

L'agent contrôle le dossier avant d'ouvrir une session. Il refuse un dossier caché ou en lecture seule, et il nomme le dossier à utiliser dans son message.

Sur Windows, l'agent ne contrôle pas la visibilité du dossier. Le chemin doit seulement être absolu, par exemple C:\restauration\test.

Donnez un dossier vide, ou un chemin qui n'existe pas encore. La commande écrit dans le dossier que vous nommez, sans autre contrôle.

Arrêter une restauration en cours

1. Tapez Ctrl+C dans la session qui a lancé la commande.
2. Lisez le code de sortie : 130 après un arrêt.

Les fichiers déjà écrits restent sur le disque. Effacez-les vous-même si vous ne les gardez pas.

Le portail n'arrête pas une restauration lancée en ligne de commande.

Suivre la restauration depuis le portail

La commande n'affiche pas d'avancement, et le portail n'a pas le statut de la restauration. Le portail montre seulement la session de lecture :

1. Ouvrez le portail.
2. Dans la barre du haut, ouvrez Endpoints.
3. Ouvrez la machine.
4. Ouvrez l'onglet Restaurations.
5. Lisez la ligne dont la colonne Origine porte Ligne de commande. Sa colonne État porte Ouverte, Fermée ou Expirée.

Le journal d'audit garde trois lignes : Restauration en ligne de commande accordée, Restauration en ligne de commande refusée et Restauration fermée. Voir Journal d'audit.

Voir aussi Suivre et arrêter une restauration pour l'onglet Restaurations.

Lire le code de sortie

Code	Ce qu'il veut dire
0	La commande a réussi.
1	La commande a échoué. Le message donne la cause.
130	Un arrêt a interrompu la restauration (Ctrl+C).

Quand la commande refuse

Les messages de la commande sont en anglais. Le tableau donne leur sens et la suite à donner.

Message	Ce qui s'est passé	Ce que vous faites
cannot contact the local agent restore service	La commande n'a pas joint le service de l'agent.	Vérifiez que le service tourne, et que vous êtes root ou administrateur.
use --list, or a snapshot ID (8 or more characters, or latest) and an absolute --target directory	Les arguments ne sont pas valides.	Donnez --list, ou un identifiant et un --target absolu.
no snapshot matches this ID; use --list to see the snapshot IDs	Aucun point ne commence par cet identifiant.	Relisez --list, puis recommencez.
more than one snapshot matches this ID; use a longer ID from --list	Plusieurs points commencent par cet identifiant.	Donnez un identifiant plus long.
restore target is not visible outside the agent service (private /tmp); use a directory under /var/lib/baastide/restore	Le dossier cible n'est visible que par le service.	Choisissez un dossier sous /var/lib/baastide/restore.
restore target is read-only for the agent service; use a directory under /var/lib/baastide/restore, then move the files	Le service ne peut pas écrire dans le dossier cible.	Restaurez sous /var/lib/baastide/restore, puis déplacez les fichiers.
agent control channel is offline	L'agent n'est pas connecté à la plateforme.	Rétablissez la liaison de la machine, puis recommencez.
restore session request timed out	La plateforme n'a pas répondu en 30 secondes.	Recommencez.
restore session denied by the backend	La plateforme a refusé la session.	Lisez la raison dans le journal d'audit, puis corrigez la cause.
restore session refused: this agent version is too old for the platform (agent_too_old)	L'agent est sous le minimum de la plateforme. Seule la mise à jour automatique passe encore.	Mettez l'agent à jour. Voir Mettre un agent à jour à la main.
restore session expired; request a new session	La session a atteint sa durée maximale.	Relancez la commande. Elle ouvre une nouvelle session.
restore failed; check repository access and target permissions	La restauration a échoué.	Vérifiez la liaison de la machine et les droits du dossier cible, puis recommencez.

Lire la raison d'un refus

1. Ouvrez le portail.
2. Dans le menu Administration, cliquez Journal d'audit.
3. Cliquez Filtres, puis choisissez l'action Restauration en ligne de commande refusée.
4. Ouvrez l'entrée de la machine, puis lisez le champ Raison.

Raison	Ce qu'elle veut dire
repo_not_ready	Le dépôt de la machine n'est pas prêt. Aucune sauvegarde n'a encore réussi, ou le dépôt est en travaux.
repo_migrating	Le dépôt de la machine change de stockage.
exclusive_job_active	Une maintenance exclusive tourne sur le dépôt. Attendez sa fin, puis recommencez.
endpoint_deleted	La suppression de la machine est demandée, ou son accès est révoqué.
agent_too_old	L'agent est sous le minimum de la plateforme.
trial_data_locked	Les données viennent d'un essai terminé. Importez une licence payante pour les restaurer.
snapshot_not_found	Le point demandé n'est pas dans le dépôt de cette machine, ou la rétention l'a supprimé.
key_unavailable	La clé du dépôt n'est pas disponible.
session_closed	La session de cette demande est déjà fermée.
session_expired	La session de cette demande est expirée.

Pour session_closed et session_expired, relancez la commande : elle ouvre une nouvelle session.

Limites et précautions

• La commande restaure des fichiers, et seulement sous un dossier cible. Elle ne remet aucun fichier à son emplacement d'origine.
• N'utilisez pas cette commande pour remettre une machine entière en service. Suivez la restauration bare metal. Voir Préparer le média de restauration.
• Une session de restauration dure 12 heures au plus. Une restauration plus longue s'arrête avec le message restore session expired. Restaurez alors un point moins volumineux, ou restaurez en plusieurs fois.
• La session donne à la machine un accès en lecture à ses points de restauration jusqu'à sa fermeture ou son expiration.
• Une restauration n'est pas limitée en débit. La limite d'envoi d'une politique ne s'applique pas. Une grosse restauration occupe donc le lien de la machine. Voir Limiter le débit d'envoi.
• La commande n'affiche pas d'avancement et ne donne pas de liste de fichiers en erreur. Le portail non plus. Un échec donne un seul message.
• Le portail n'arrête pas une restauration lancée en ligne de commande.
• La date de --list est relevée sur la machine. Le portail affiche la date relevée par la plateforme. Les deux peuvent différer.
• Un client qui a coupé les restaurations depuis le portail (portal_restore = false dans agent.conf) n'empêche pas cette commande.
• La commande baastide restic-restore est la commande d'origine de restic. Ce n'est pas une session BaaStide : elle demande les accès du dépôt. Ne l'utilisez pas.
• L'option --socket ne sert que lorsque le service de l'agent écoute à un autre endroit, parce qu'il a été lancé avec --restore-socket. Sinon, ne la donnez pas.
• Le mot de passe du dépôt et le jeton d'accès ne passent jamais dans la commande, ni dans une variable d'environnement, ni dans un fichier.
• Les messages de la commande ne contiennent jamais la réponse du stockage : elle peut porter un secret.

Référence

• CLI de l'agent : baastide restore.
• CLI de l'agent : baastide version, pour lire la version installée sur la machine.
• Versions d'agent minimales par fonction.