Module stat Ansible : info sur fichiers et dossiers

ansible.builtin.stat: retourne des informations sur un fichier ou dossier sans le modifier : existence, type, taille, mode, owner, checksum, mtime. C'est le module n°1 de la logique conditionnelle Ansible, combiné avec register: + when:, il permet de coder des branches sûres.

stat: est lecture seule par définition, toujours changed=0.

Ce que vous allez apprendre

• Vérifier l'existence d'un fichier avant d'agir dessus.
• Distinguer les types : fichier régulier, dossier, symlink, hardlink.
• Comparer des checksums SHA256 pour détecter une modification.
• Mesurer la taille et le mtime pour des contrôles de conformité.
• Diagnostiquer un fichier symlink qui pointe vers le vide.

Prérequis

• Connaître register: et when: (cf. Lab 16, register et set_fact).

Stat de base

- name: Stat sur /etc/passwd
  ansible.builtin.stat:
    path: /etc/passwd
  register: passwd_stat

- name: Inspecter le resultat
  ansible.builtin.debug:
    var: passwd_stat.stat

passwd_stat.stat est un dict qui contient : exists, isfile, isdir, islnk, size, mode, uid, gid, pw_name, gr_name, mtime, etc.

Pattern conditionnel stat: + when:

- name: Stat sur un fichier optionnel
  ansible.builtin.stat:
    path: /etc/myapp.conf
  register: myapp_conf

- name: Action SI le fichier existe
  ansible.builtin.copy:
    src: /etc/myapp.conf
    dest: /tmp/backup.conf
    remote_src: true
    mode: "0644"
  when: myapp_conf.stat.exists

- name: Action SI le fichier n existe PAS
  ansible.builtin.copy:
    content: "Default config\n"
    dest: /etc/myapp.conf
    mode: "0644"
  when: not myapp_conf.stat.exists

Pattern branche conditionnelle classique : avant toute opération sur un fichier qui peut ou non exister, on stat puis on décide.

Types de fichiers

Le module ne rend pas un champ « type » mais une série de booléens, un par nature d'objet. C'est la façon sûre de brancher un playbook : déduire le type d'un autre champ trompe, puisqu'un dossier porte une taille qui ne décrit pas son contenu et qu'un lien physique ressemble en tout point à un fichier ordinaire. Le tableau donne, pour chaque nature, le champ à tester et ceux qui n'ont de sens que pour elle.

Type	Champs distinctifs
Fichier régulier	isfile: true, size, checksum
Dossier	isdir: true (pas de size significatif)
Symlink	islnk: true, lnk_source (cible), lnk_target (chemin résolu)
Hardlink	nlink > 1 (nombre de liens)
Block/char device	isblk: true / ischr: true

Glissez pour voir

Checksum pour détection de modification

- name: Stat avec checksum SHA256
  ansible.builtin.stat:
    path: /etc/passwd
    get_checksum: true
    checksum_algorithm: sha256
  register: passwd_check

- name: Afficher le checksum
  ansible.builtin.debug:
    msg: "SHA256 : {{ passwd_check.stat.checksum }}"

Attention performance : get_checksum: true calcule le hash en lisant tout le fichier. Sur un fichier de 1Go, c'est lent. À utiliser uniquement quand vous avez besoin du checksum.

Algorithmes supportés : sha1 (défaut), sha256 (recommandé), sha512, md5 (déprécié).

Mtime et tests temporels

- name: Stat avec mtime
  ansible.builtin.stat:
    path: /etc/passwd
  register: passwd_mtime

- name: Verifier que /etc/passwd n a pas ete modifie depuis 24h
  ansible.builtin.assert:
    that:
      - (ansible_date_time.epoch | int - passwd_mtime.stat.mtime | int) < 86400
    fail_msg: "ALERTE : /etc/passwd modifie depuis moins de 24h"

mtime est un timestamp Unix. Pour comparer, soustraire et tester en secondes. Utile pour des audits de sécurité.

Symlink et follow:

Par défaut, stat: ne suit pas les symlinks. Le symlink lui-même existe (exists: true), mais sa cible peut être absente :

- name: Relever l'état de mon-symlink-casse
  ansible.builtin.stat:
    path: /tmp/mon-symlink-casse
  register: link_stat
  # → exists: true, islnk: true, MAIS cible non vérifiée

Pour suivre le lien :

- name: Relever l'état de mon-symlink-casse
  ansible.builtin.stat:
    path: /tmp/mon-symlink-casse
    follow: true
  register: link_stat_follow
  failed_when: false   # follow + cible absente → erreur sinon

Avec follow: true, exists: false si la cible n'existe pas.

Pièges courants

Ces trois symptômes partagent une même origine : un champ exploité sans avoir vérifié ce qu'il décrit. L'empreinte coûte la lecture intégrale du fichier et ne se demande donc que si une comparaison de contenu est réellement en jeu, un lien symbolique répond pour lui-même tant que follow: reste à sa valeur par défaut, et la taille d'un dossier reflète la structure du système de fichiers, pas ce qu'il contient.

Symptôme	Cause	Fix
Performance dégradée	get_checksum: true sur gros fichiers	Désactiver sauf besoin réel
Symlink considéré "existant" alors qu'il pointe vers le vide	follow: false (défaut)	Ajouter follow: true ou stat sur la cible
passwd_stat.stat.size introuvable sur dossier	Dossiers n'ont pas de size significatif	Vérifier isdir avant d'accéder à size

Glissez pour voir

Contrôle de connaissances

Vérifiez que l'essentiel de ce guide est acquis. Les questions portent uniquement sur ce qui vient d'être expliqué ici.

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

6 questions

6 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

À retenir

• stat: = lecture seule, toujours changed=0.
• register: + when: var.stat.exists = pattern de logique conditionnelle.
• isfile, isdir, islnk = distinction des types.
• get_checksum: true = lecture complète du fichier (lent sur gros fichiers).
• follow: false (défaut) = stat sur le symlink lui-même, pas la cible.

Mettre en pratique

Le module stat sert à décider, pas à modifier, encore faut-il interroger les bons champs. Le lab vous fait inspecter trois fichiers système de db1.lab, dont un avec get_checksum: true, puis assembler un rapport à partir des valeurs enregistrées. Les tests relisent ce rapport et contrôlent le checksum SHA256, l'UID 0 attendu sur /etc/shadow et la présence des trois entrées, sans qu'aucun fichier source ait été touché.

Lab pratique

Module stat : inspecter fichiers et dossiers

$ dsoxlab run modules-diagnostic-stat

Environnement : VM·Durée : ~30 min

Validé : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que dsoxlab et comment l'installer

dsoxlab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/ansible-training

Lancer ce lab, puis valider votre travail :

dsoxlab run modules-diagnostic-stat
dsoxlab check modules-diagnostic-stat

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille l'installation, le calcul du score et les pièges.

Pour aller plus loin

• Modules assert et fail : Transformer un stat en précondition bloquante, avec un message d'échec lisible.
• Module service_facts : La même logique de lecture pure, appliquée cette fois à l'état des services.
• raw, command, shell, script : Les options creates et removes, qui remplacent souvent un couple stat plus when.

×

📖 Voir la documentation →