--- title: Comprendre les verrous sur les dépôts description: "Cybee repose sur le moteur de sauvegarde Restic pour gérer les opérations de lecture et d'écriture dans les dépôts. Ce moteur intègre un mécanisme natif de verrouillage (*locking*) qui protège l'intégrité des dépôts lors des opérations concurrentes. Comprendre la distinction…" url: "https://cybee.fr/documents/verrou-depot/" updated: "2026-07-16" category: Architecture technique --- # Comprendre les verrous sur les dépôts Cybee repose sur le moteur de sauvegarde Restic pour gérer les opérations de lecture et d'écriture dans les dépôts. Ce moteur intègre un mécanisme natif de verrouillage (*locking*) qui protège l'intégrité des dépôts lors des opérations concurrentes. Comprendre la distinction entre locks exclusifs et non exclusifs est utile notamment pour diagnostiquer les comportements bloquants sur les dépôts partagés Cybee. --- ## Qu'est-ce qu'un verrou sur un dépot ? Lorsque Cybee exécute une opération sur un dépôt, il crée un fichier de verrou (*lock file*) dans le répertoire `locks/` du dépôt. Ce mécanisme garantit qu'aucune opération incompatible ne se déroule simultanément, ce qui pourrait corrompre les données ou produire des résultats incohérents. Un verrou contient les métadonnées suivantes : - L'identifiant de processus (PID) du processus ayant posé le verrou - Le nom d'hôte de la machine source - L'utilisateur ayant lancé l'opération - L'horodatage de création du verrou - Le type de verrou : exclusif ou non exclusif --- ## Les verrou non exclusifs (*shared locks*) ### Définition Un verrou non exclusif est posé lors des opérations qui se contentent de **lire** le dépôt sans le modifier structurellement. Plusieurs opérations peuvent détenir simultanément un lock non exclusif sur le même dépôt. ### Opérations concernées Les commandes qui posent un verrou non exclusif sont notamment : - `backup` — création d'un nouveau cliché (lecture des données existantes pour la déduplication) - `restore` — restauration d'un cliché - `check` — vérification de l'intégrité du dépôt (mode lecture seule) - `ls` — listage du contenu d'un cliché - `dump` — extraction de fichiers depuis un cliché ### Comportement en parallèle Plusieurs sauvegardes Cybee peuvent s'exécuter simultanément sur un même dépôt partagé, chacune détenant son propre verrou non exclusif. C'est ce qui permet à Cybee de faire tourner plusieurs agents en parallèle sur un dépôt commun. > **Point clé métier** : dans un contexte de dépôt partagé Cybee avec plusieurs agents, plusieurs sauvegardes peuvent coexister sans blocage. Ce comportement est attendu et voulu. --- ## Les verrou exclusifs (*exclusive locks*) ### Définition Un verrou exclusif est posé lors des opérations qui **modifient la structure du dépôt** de manière globale. Une seule opération peut détenir un verrou exclusif à la fois. Toute autre opération — qu'elle soit exclusive ou non exclusive — est **bloquée** tant que le verrou exclusif est actif. ### Opérations concernées Les commandes qui posent un verrou exclusif sont notamment : - `prune` — suppression des données orphelines (packs non référencés) - `rebuild-index` — reconstruction de l'index du dépôt - `repair` — réparation du dépôt après une anomalie - `cache --cleanup` (selon les versions) ### Comportement en cas de conflit Si un agent Cybee tente de lancer une sauvegarde pendant qu'un `prune` est en cours sur le même dépôt, il recevra une erreur du type : ``` Fatal: unable to create lock in backend: repository is already locked exclusively ``` L'opération sera mise en échec jusqu'à la libération du verrou exclusif. > **Point clé métier** : un `prune` en cours sur un dépôt partagé bloque toutes les sauvegardes des autres agents sur ce dépôt. Il faut planifier les opérations de maintenance (prune, rebuild-index) en dehors des fenêtres de sauvegarde. --- ## Verrous orphelins (*stale locks*) ### Origine Un verrou orphelin est un verrou qui subsiste dans le dépôt alors que le processus qui l'avait créé ne s'exécute plus. Cela peut survenir dans les cas suivants : - Arrêt brutal de l'agent (crash, coupure réseau, kill forcé) - Extinction de la machine sans attendre la fin de l'opération - Timeout de connexion au stockage objet ### Conséquence Un verrou orphelin exclusif bloque **indéfiniment** toutes les opérations sur le dépôt, y compris les nouvelles sauvegardes, jusqu'à sa suppression manuelle. ### Détection Pour lister les verrous présents sur un dépôt : ``` locks ``` Il est affiché chaque verrou avec son type (exclusif ou non), son PID, l'hôte source et la date de création. ### Suppression Pour supprimer les verrous orphelins : ``` unlock ``` Cette commande supprime tous les verrous dont on ne peut pas vérifier que le processus est encore actif. > ⚠️ **Précaution** : ne jamais exécuter `unlock` si une opération légitime est en cours sur le dépôt. Cela pourrait conduire à une exécution concurrente d'opérations incompatibles et à une corruption du dépôt. --- ## Implications  | Situation | Type de lock | Impact opérationnel | | --- | --- | --- | | Plusieurs agents sauvegardent en parallèle | Non exclusifs | Aucun blocage — comportement normal | | Un prune est lancé pendant une sauvegarde | Exclusif vs Non exclusif | La sauvegarde attend | | Crash d'un agent pendant une sauvegarde | verrou orphelin | Blocage potentiel des autres agents | | Rebuild-index en cours | Exclusif | Toutes les opérations sont bloquées | ### Recommandations pour la planification  1. **Planifier les opérations de prune en dehors des fenêtres de sauvegarde** des autres agents sur le même dépôt partagé. 2. **Monitorer les verrous** **orphelins** : mise en place une alerte si un lock de type exclusif dépasse une durée anormale (ex. > 2 heures). 3. **Procédure de déblocage** : en cas de verrou orphelin confirmé, exécuter `unlock` depuis un poste habilité avec les credentials du dépôt, après avoir vérifié qu'aucune opération légitime n'est en cours. 4. **Traçabilité** : les métadonnées du verrou (hôte, utilisateur, PID, date) permettent d'identifier rapidement l'origine du blocage avant toute intervention. --- ## Points clés - La sauvegarde distingue deux types de verrous : - **non exclusifs** (opérations de lecture / sauvegarde) - **exclusifs** (opérations de maintenance structurelle). - Les verrous non exclusifs sont **compatibles entre eux** : plusieurs sauvegardes peuvent coexister sur un dépôt partagé. - Les verrous exclusifs bloquent **toutes** les autres opérations le temps de leur exécution. - Les verrous orphelins peuvent survenir après un crash et doivent être nettoyés via `restic unlock` avec précaution. - Dans le contexte Cybee, la gestion desverrous locks est particulièrement important sur les **dépôts partagés** (multi-agents).