Annexe A. Recommandations pour les implémenteurs

Cette annexe fournit des conseils non normatifs aux implémenteurs du protocole syslog.

A.1. Relation avec le syslog BSD

La RFC 3164 décrivait le protocole syslog BSD, largement déployé depuis de nombreuses années. Le présent document rend obsolète la RFC 3164, tout en conservant une compatibilité significative.

Différences principales :

• Champ VERSION : cette spécification ajoute un champ VERSION explicite. Les implémentations historiques ne le reconnaîtront pas.

• Format de TIMESTAMP : cette spécification utilise le format d'horodatage de la RFC 3339 avec date complète, fuseau horaire et fractions de seconde optionnelles. La RFC 3164 utilisait un format plus simple, sans année ni fuseau horaire.

• STRUCTURED-DATA : cette spécification introduit les éléments de structured data. La RFC 3164 ne possédait pas de mécanisme équivalent.

• Format de MSG : le champ TAG de la RFC 3164 a été scindé en APP-NAME, PROCID et MSGID dans le HEADER.

Considérations d'interopérabilité :

Lors de la communication avec des systèmes RFC 3164 :

• Émission vers des systèmes hérités : formater les messages selon la RFC 3164 si le receveur ne supporte pas la présente spécification. Le transport sender devrait détecter les capacités du receveur ou permettre une configuration.

• Réception depuis des systèmes hérités : un receveur conforme à cette spécification devrait pouvoir analyser les messages RFC 3164. Il peut les transformer dans le format défini par ce document.

• Comportement de relais : les relais devront parfois transformer les messages d'un format à l'autre. Lors de la conversion de cette spécification vers la RFC 3164 :

  • Retirer le champ VERSION.
  • Convertir TIMESTAMP au format MMM JJ HH:MM:SS.
  • Supprimer fuseau horaire et année.
  • Supprimer STRUCTURED-DATA ou l'ajouter à MSG.
  • Reconstruire TAG à partir de APP-NAME et PROCID.

• Conversion de la RFC 3164 vers cette spécification :

  • Mettre VERSION à 1.
  • Ajouter l'année courante à l'horodatage.
  • Utiliser le fuseau horaire du relais ou UTC.
  • Analyser TAG en APP-NAME et PROCID (au mieux).
  • Mettre MSGID à NILVALUE si non déterminable.

A.2. Longueur des messages

La capacité minimale exigée du receveur, 480 octets, a des implications pratiques :

Pourquoi 480 octets ?

• Tient dans un seul paquet UDP non fragmenté sur de nombreux réseaux.
• Probabilité de livraison plus élevée sur des réseaux dégradés.
• Compatibilité avec les implémentations limitées.

Implications :

• Messages critiques : les alertes de sécurité et urgences opérationnelles devraient tenir dans 480 octets.
• Données de dépannage : garder les messages de diagnostic concis.
• Données importantes en premier : placer les informations critiques tôt dans le message.

Messages plus longs :

De nombreux déploiements modernes acceptent des messages bien plus volumineux :

• TLS autorise typiquement des dizaines voire des centaines de kilo-octets.
• TCP n'a pas de limite pratique.
• Les implémentations modernes acceptent souvent 2048, 8192 octets ou plus.

Bonnes pratiques :

• Configurer la taille maximale en fonction du déploiement.
• Utiliser STRUCTURED-DATA pour les métadonnées importantes (compté dans la longueur du message).
• Tester les tailles maximales dans votre environnement.
• Gérer proprement les messages surdimensionnés (troncature ou rejet).
• Surveiller les messages tronqués au niveau des collectors.

Considérations UTF-8 :

La longueur du message se mesure en octets, pas en caractères. Une chaîne UTF-8 de 1000 caractères peut faire 3000 octets ou plus si elle contient des caractères non ASCII. Les implémenteurs doivent en tenir compte dans le dimensionnement.

A.3. Valeurs de Severity

Une utilisation appropriée des valeurs de Severity améliore l'utilité des messages.

Recommandations :

• Emergency (0) : à utiliser avec parcimonie pour de véritables urgences.

  • Système totalement inutilisable.
  • Défaillance imminente d'un matériel critique.
  • Perte de données en cours.

• Alert (1) : action immédiate requise.

  • Interruption de service.
  • Brèche de sécurité détectée.
  • Épuisement imminent de ressources critiques.

• Critical (2) : conditions critiques.

  • Panne de disque.
  • Connexion réseau principale perdue.
  • Plantage d'application.

• Error (3) : conditions d'erreur.

  • Défaillances de services non critiques.
  • Erreurs récupérables.
  • Délais d'attente de connexion.

• Warning (4) : conditions d'avertissement.

  • Utilisation de ressources approchant les limites.
  • Usage de fonctionnalités obsolètes.
  • Problèmes de configuration.

• Notice (5) : normal mais significatif.

  • Démarrage/arrêt de service.
  • Modifications de configuration.
  • Événements normaux pertinents pour la sécurité.

• Informational (6) : messages informationnels.

  • Opérations de routine.
  • Messages d'état.
  • Établissement de connexion.

• Debug (7) : messages de niveau débogage.

  • Informations de diagnostic détaillées.
  • Messages destinés aux développeurs.
  • Devraient être désactivés en production.

Considérations de configuration :

Permettre aux administrateurs de :

• Ajuster les attributions de Severity selon les besoins du déploiement.
• Filtrer les messages par Severity.
• Router les Severity vers différents collectors.
• Surcharger la Severity pour des types de messages spécifiques.

Éviter les abus de Severity :

• Ne pas marquer tous les messages en Emergency.
• Ne pas utiliser Debug pour des événements de production.
• Tenir compte de la fatigue d'alerte des opérateurs.

A.4. Précision de TIME-SECFRAC

Le champ TIMESTAMP supporte des fractions de seconde jusqu'à 6 chiffres (microsecondes).

Erreurs courantes :

Suppression des zéros de tête :

INCORRECT : 2003-10-11T22:13:14.3      (semble être 300 ms)
CORRECT   : 2003-10-11T22:13:14.003    (réellement 3 ms)

Recommandations de précision :

• Utiliser les millisecondes (3 chiffres) pour la plupart des applications.
• Utiliser les microsecondes (6 chiffres) pour les besoins de haute précision.
• Omettre les fractions de seconde si la précision sub-seconde n'est pas nécessaire.
• S'assurer que la synchronisation horaire (NTP) supporte la précision requise.

Notes d'implémentation :

Tous les systèmes ne fournissent pas une précision microseconde. Il est acceptable de :

• Fournir une précision moindre que 6 chiffres.
• Arrondir ou tronquer à la précision disponible.
• Omettre TIME-SECFRAC entièrement si la précision n'est pas disponible.

A.5. Convention de casse pour les noms

Ce document utilise la « lower camel case » pour les SD-ID et PARAM-NAME.

Convention :

• Première lettre en minuscule.
• Première lettre des mots suivants en majuscule.
• Pas de tirets ni de soulignements.

Exemples :

• timeQuality
• syncAccuracy
• enterpriseId
• myCompanyName

Avantages :

• Cohérence entre implémentations.
• Lisibilité.
• Compatibilité avec divers langages de programmation.

Recommandations :

À utiliser pour :

• Les nouveaux SD-ID.
• Les PARAM-NAME.
• Les identifiants d'extension.

Les implémentations privées peuvent recourir à d'autres conventions, mais la cohérence est recommandée.

A.6. Applications syslog sans connaissance de l'heure

La section 6.2.3 autorise NILVALUE pour TIMESTAMP lorsque l'heure est inconnue.

Quand utiliser NILVALUE pour TIMESTAMP :

• Systèmes embarqués sans horloge en temps réel.
• Messages au démarrage avant la synchronisation horaire.
• Systèmes pour lesquels la récupération de l'heure a échoué.

Quand NE PAS utiliser NILVALUE :

• Lorsque le système d'exploitation fournit des fonctions horaires.
• Lorsqu'une implémentation paresseuse cherche à éviter la gestion de l'heure.
• Lorsque l'heure est disponible mais peu pratique à obtenir.

Bonnes pratiques :

• Émettre des TIMESTAMP valides chaque fois que possible.
• N'utiliser NILVALUE que lorsqu'il est réellement impossible d'obtenir l'heure.
• Tenir compte des compromis entre fuseau horaire et précision.
• Documenter la gestion de l'heure dans votre implémentation.

Gestion par le relai :

Les relais qui reçoivent des messages avec NILVALUE comme TIMESTAMP peuvent :

• Les transmettre tels quels.
• Les remplacer par l'heure courante du relai.
• Les rejeter (si la politique exige des horodatages).

La configuration devrait piloter ce comportement.

A.7. Notes sur le SD-ID timeQuality

Le SD-ID timeQuality fournit des métadonnées précieuses sur la précision des horodatages.

Paramètre tzKnown :

La valeur par défaut devrait être 0 (inconnu) sauf si :

• L'administrateur a explicitement configuré le fuseau horaire.
• Le système d'exploitation fournit une information de fuseau horaire fiable.
• Le système a validé son fuseau horaire à partir d'une source externe.

Paramètre isSynced :

Le mettre à 1 uniquement quand :

• NTP ou une autre synchronisation horaire est active.
• La synchronisation est vérifiée comme réussie.
• La source horaire est de confiance.

Paramètre syncAccuracy :

Ne le fournir que lorsque :

• La précision réelle est connue (à partir des statistiques NTP).
• L'administrateur a configuré la précision attendue.
• Des données de mesure étayent la valeur indiquée.

Ne pas surestimer la précision :

Une fausse précision nuit à la confiance accordée aux journaux. Il est préférable de :

• Omettre timeQuality s'il y a incertitude.
• Fournir des estimations de précision conservatrices.
• Documenter les revendications de précision.

A.8. Encodage UTF-8 et BOM

Le BOM (Byte Order Mark) signale un encodage UTF-8 dans le champ MSG.

Détails du BOM :

• Séquence d'octets : 0xEF 0xBB 0xBF
• Apparaît au début du champ MSG.
• Indique qu'un texte UTF-8 suit.

Quand inclure le BOM :

• Quand MSG contient du texte encodé en UTF-8.
• Quand l'encodage UTF-8 est certain.
• Pour la cohérence avec la politique de l'organisation.

Quand omettre le BOM :

• Quand l'encodage de MSG est inconnu ou incertain.
• Quand MSG contient des données binaires.
• Pour la rétrocompatibilité avec des systèmes ne gérant pas le BOM.

Gestion par le receveur :

Les receveurs devraient :

• Détecter la présence du BOM.
• Traiter UTF-8 en conséquence.
• Gérer les messages sans BOM (encodage supposé inconnu).
• Ne pas afficher le BOM aux utilisateurs.

Gestion par le relai :

Les relais qui transmettent des messages devraient :

• Préserver le BOM s'il est présent.
• Ne pas ajouter de BOM, sauf transcodage vers UTF-8.
• Ne pas retirer le BOM, sauf transcodage vers un autre encodage.