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.

- ansible.builtin.stat:
    path: /etc/myapp.conf
  register: myapp_stat

- name: Backup avant modification (uniquement si le fichier existe et n'est pas vide)
  ansible.builtin.copy:
    src: /etc/myapp.conf
    dest: "/etc/myapp.conf.backup-{{ ansible_date_time.iso8601_basic_short }}"
    remote_src: true
    owner: root
    group: root
    mode: "0600"
  when:
    - myapp_stat.stat.exists
    - myapp_stat.stat.size > 0
  become: true

Champs courants : .stat.exists, .stat.isfile, .stat.isdir, .stat.islnk, .stat.size, .stat.mode, .stat.checksum, .stat.mtime. Pas de get_checksum: false par défaut sur les gros fichiers (lent), mais activer explicitement pour valider intégrité.

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
  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

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`

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 :

- 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 :

- 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

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`

À 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.

Pratiquer dans le lab

Cette page a un lab d'accompagnement : labs/modules-diagnostic/stat/ dans stephrobert/ansible-training.

Challenge, sur db1.lab :

Stat 3 fichiers système (/etc/passwd avec checksum, /etc/shadow, /etc/sudoers).
Générer un rapport /tmp/lab-stat-report.txt.

Validation pytest+testinfra :

ansible-playbook solution.yml
pytest -v labs/modules-diagnostic/stat/challenge/tests/

4 tests vérifient le rapport, le checksum SHA256, l'UID 0 sur shadow, et la présence des 3 fichiers.

Prochaines étapes

Module find Pour rechercher MULTIPLES fichiers par pattern (stat: prend un seul path)

Module assert Combiner stat: + assert: pour valider les attributs (mode, owner, taille)

Pivot Modules Vue d'ensemble des modules diagnostic, fichiers, paquets, RHEL système