Compatibilité du journal

Le lecteur 1.3.3 accepte les schémas 1 et 2, y compris dans les mêmes archives. L’adaptation se fait en mémoire : aucun script de migration n’est nécessaire pour ces formats.

Schémas pris en charge

schema_version est indépendant de la version du logiciel et de api_version. La 0.0.65 publiée écrivait déjà le schéma 2 et lisait les deux formats. Le schéma 1 correspond au format historique antérieur.

Lire ne réécrit ni ne répare les fichiers de données ; le fichier de verrouillage associé peut être créé. Les écritures et la rotation habituelles continuent à limiter la durée de conservation.

Valeurs et identité des événements

Les identifiants, corrélations, dates et valeurs sont conservés. Les textes utilisent les échappements visibles communs au journal : caractères de contrôle et préfixes de formules protégés, barres obliques inverses littérales doublées, Unicode imprimable préservé. Afficher le texte obtenu après lecture du JSON sans interpréter à nouveau ces échappements.

Les champs scalaires supplémentaires sont acceptés, les objets et tableaux imbriqués sont rejetés. Les champs absents ne sont pas ajoutés. Ce contrôle du format et des textes ne valide pas toute la signification ni tous les types des champs. Prévoir les valeurs absentes, nulles et les libellés inconnus sans les assimiler à un succès.

Les motifs restent en anglais. Un événement started sans résultat conserve une issue inconnue : aucune action n’est rejouée pour compléter l’historique.

Lectures et exports

audit-export lit tous les fichiers retenus, du plus ancien au plus récent, puis applique ses filtres. L’interface HTTP parcourt des pages bornées en ordre inverse ; son export concerne la page demandée.

Le JSONL normalisé conserve les champs supplémentaires et les types numériques ou nuls. Il ne remplace pas une sauvegarde à l’identique des fichiers d’origine. Un nouvel export n’ajoute pas de couche d’échappement.

Le CSV utilise des colonnes fixes : les champs inconnus sont omis, les nombres deviennent du texte et les valeurs absentes ou nulles deviennent des cellules vides. Il sert à l’analyse, pas à une restauration sans perte. Il n’existe pas de commande d’import CSV.

Erreurs et portée du contrôle

Un schéma inconnu, un JSON invalide, un texte non conforme ou un événement tronqué interrompt la lecture lorsqu’il est rencontré. La commande renvoie 119 avant les données exportées pour ces erreurs de lecture, même si un filtre aurait exclu l’événement. Vérifier toujours le code de sortie : une autre erreur, notamment d’écriture de l’export, peut laisser un résultat partiel.

La lecture HTTP renvoie 503 audit_unavailable si un événement parcouru est invalide, y compris lorsqu’un filtre l’exclut. Une page récente lisible ne certifie pas les archives plus anciennes non parcourues. Les limites et curseurs figurent dans le contrat HTTP.

Une écriture vérifie le saut de ligne final du fichier actif, sans analyser tout l’historique. Son succès ne prouve donc pas l’intégrité des archives. En cas de corruption, arrêter les processus qui écrivent et conserver les fichiers originaux avant toute intervention ; un export normal peut échouer sur ces fichiers.

Mise à niveau et retour arrière

1. Noter les versions exactes, chemins et paramètres de rétention. Arrêter tous les processus qui écrivent, puis sauvegarder les répertoires persistants, les archives, la configuration et les états d’actions concernés, avec leurs droits.
2. Tester le lecteur cible sur une copie, avec les mêmes limites. Vérifier le code de sortie, les identifiants, le nombre d’événements et quelques textes représentatifs. Ne jamais rediriger un export vers son propre fichier d’entrée.
3. Mettre à niveau l’agent et l’interface correspondante, conserver les volumes et paramètres, puis vérifier la collecte, le journal et les exports.
4. Pour revenir en arrière, arrêter les écritures et conserver séparément les données produites depuis la mise à niveau. Tester l’ancien lecteur sur une copie avant reprise. Restaurer une ancienne sauvegarde exclut les événements ultérieurs ; les garder séparément sans rejouer les actions.

Exemple avec une copie dans /srv/monit-audit-check, les limites par défaut et la commande de la version cible :

umask 077
monit-docker --audit-file /srv/monit-audit-check/events.jsonl \
  --audit-max-bytes 5242880 --audit-files 5 \
  audit-export > /srv/monit-audit-check-export.jsonl

Adapter les limites à la configuration d’origine. La 0.0.65 publiée utilisait 10 Mio par fichier par défaut, contre 5 Mio depuis la 0.0.66. Réduire cette limite ne réduit pas les archives existantes et peut empêcher leur lecture complète. Réduire le nombre de fichiers exclut les archives au-delà de cette plage sans les supprimer.

Évolutions futures

Préserver les identifiants, le sens des champs et l’encodage dans un même schéma. Tester les ajouts de champs avec les anciens lecteurs. Tout changement incompatible de structure, d’encodage ou de signification doit faire l’objet d’une décision explicite sur le schéma, avec versions prises en charge et limites du retour arrière.

Privilégier l’adaptation à la lecture lorsqu’elle préserve l’information. Si une conversion physique devient nécessaire, fournir avant son activation un outil explicite avec simulation, sauvegarde des sources, sortie séparée, contrôle des identifiants et du nombre d’événements, et reprise après interruption. Depuis la 0.0.78, la commande facultative audit-migrate fournit une simulation et une conversion explicite avec sauvegarde, sans remplacer le journal actif.

Validation et limites

Les tests de formats et les essais de mise à niveau depuis 0.0.78, 0.0.79 et 0.0.82 accompagnent la publication 1.0.0. Ils ne certifient pas toutes les versions ni tous les déploiements. Voir les résultats et limites.