Appendice A. Lignes directrices pour les implémenteurs

Cette annexe fournit des directives non normatives à l'attention des implémenteurs du protocole syslog.

A.1. Relation avec BSD Syslog

La RFC 3164 décrivait le protocole BSD syslog, déployé de manière très répandue pendant de nombreuses années. Le présent document rend la RFC 3164 obsolète, tout en préservant une compatibilité importante.

Principales différences :

• Champ VERSION : la présente spécification ajoute un champ VERSION explicite. Les implémentations anciennes ne reconnaîtront pas ce champ.

• Format TIMESTAMP : la présente spécification utilise des horodatages RFC 3339 comportant la date complète, le fuseau horaire et, éventuellement, une partie fractionnaire des secondes. La RFC 3164 utilisait un format plus simple, sans année ni fuseau horaire.

• STRUCTURED-DATA : la présente spécification introduit des éléments de données structurées. La RFC 3164 ne disposait d'aucun mécanisme équivalent.

• Format MSG : le champ TAG de la RFC 3164 a été scindé en des champs APP-NAME, PROCID et MSGID au sein de l'HEADER.

Considérations d'interopérabilité :

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

• Envoi vers des systèmes anciens : si le récepteur ne prend pas en charge la présente spécification, formater les messages selon la RFC 3164. L'expéditeur de transport doit détecter les capacités du récepteur ou permettre une configuration.

• Réception depuis des systèmes anciens : un récepteur conforme à la présente spécification doit être capable d'analyser les messages de la RFC 3164. Le récepteur peut les convertir dans le format défini dans le présent document.

• Comportement des relais : un relais peut avoir besoin de convertir les messages d'un format à l'autre. Lors de la conversion de la présente spécification vers la RFC 3164 :

  • supprimer le champ VERSION ;
  • convertir TIMESTAMP au format MMM DD HH:MM:SS ;
  • supprimer le fuseau horaire et l'année ;
  • supprimer STRUCTURED-DATA ou l'ajouter à MSG ;
  • reconstruire TAG à partir de APP-NAME et PROCID.

• Conversion de la RFC 3164 vers la présente spécification :

  • définir VERSION à 1 ;
  • ajouter l'année en cours à l'horodatage ;
  • utiliser le fuseau horaire du relais ou UTC ;
  • analyser TAG en APP-NAME et PROCID (au mieux) ;
  • définir MSGID à NILVALUE si cela n'est pas déterminable.

A.2. Longueur du message (Message Length)

La capacité minimale requise de 480 octets pour le récepteur revêt une signification pratique :

Pourquoi 480 octets ?

• un seul paquet UDP sans fragmentation sur de nombreux réseaux ;
• une probabilité de livraison accrue sur les réseaux dégradés ;
• la compatibilité avec des implémentations limitées.

Incidences :

• Messages critiques : les alertes de sécurité et les urgences opérationnelles doivent tenir dans 480 octets ;
• Données de dépannage : conserver les messages de diagnostic compacts ;
• Données importantes en priorité : placer les informations essentielles au début du message.

Messages plus longs :

De nombreux déploiements modernes prennent en charge des messages plus longs :

• le transport TLS permet généralement des dizaines ou des centaines de kilo-octets ;
• le transport TCP n'a pas de limite de taille pratique ;
• les implémentations modernes prennent souvent en charge des messages de 2048, 8192 octets ou plus.

Bonnes pratiques :

• configurer la taille maximale des messages selon les exigences du déploiement ;
• utiliser STRUCTURED-DATA pour les métadonnées importantes (comptabilisées dans la longueur du message) ;
• tester la taille maximale des messages dans votre environnement ;
• mettre en œuvre un traitement élégant des messages de taille excessive (troncation ou rejet) ;
• surveiller les messages tronqués au niveau du collecteur.

Considérations relatives à UTF-8 :

La longueur du message est mesurée en octets et non en caractères. Si elle contient des caractères non ASCII, une chaîne UTF-8 de 1000 caractères peut occuper 3000 octets ou plus. Les implémentateurs doivent en tenir compte lors de la détermination de la taille des messages.

A.3. Valeurs de sévérité (Severity Values)

L'utilisation correcte des valeurs de sévérité améliore l'utilité des messages.

Recommandations :

• Emergency (0) : à utiliser avec prudence pour de véritables situations d'urgence

  • le système est totalement indisponible ;
  • un matériel critique est sur le point de tomber en panne ;
  • une perte de données est en cours.

• Alert (1) : nécessite une action immédiate

  • interruption de service ;
  • faille de sécurité détectée ;
  • ressource critique sur le point d'être épuisée.

• Critical (2) : situation critique

  • défaillance de disque dur ;
  • perte de la connexion réseau principale ;
  • plantage d'application.

• Error (3) : situation d'erreur

  • défaillance de services non critiques ;
  • erreurs récupérables ;
  • expiration de délai de connexion.

• Warning (4) : situation d'avertissement

  • utilisation des ressources proche des limites ;
  • fonctionnalité obsolète utilisée ;
  • problème de configuration.

• Notice (5) : situation normale mais importante

  • démarrage/arrêt de service ;
  • modification de configuration ;
  • événement normal lié à la sécurité.

• Informational (6) : message d'information

  • opérations courantes ;
  • messages d'état ;
  • établissement de connexion.

• Debug (7) : message de niveau débogage

  • informations de diagnostic détaillées ;
  • messages destinés aux développeurs ;
  • doivent être désactivés en production.

Considérations de configuration :

Permettre à l'administrateur :

• d'ajuster l'attribution des sévérités selon les besoins du déploiement ;
• de filtrer les messages par sévérité ;
• d'acheminer les sévérités vers des collecteurs différents ;
• de remplacer la sévérité pour certains types de messages.

Éviter l'abus des sévérités :

• ne pas marquer tous les messages comme Emergency ;
• ne pas utiliser la sévérité 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 prend en charge une partie fractionnaire des secondes allant jusqu'à 6 chiffres (microsecondes).

Erreurs fréquentes :

Suppression des zéros de tête :

ERREUR : 2003-10-11T22:13:14.3      (semble correspondre à 300 ms)
CORRECT : 2003-10-11T22:13:14.003    (correspond en réalité à 3 ms)

Recommandations de précision :

• utiliser les millisecondes (3 chiffres) pour la plupart des applications ;
• utiliser les microsecondes (6 chiffres) pour un cadrage de haute précision ;
• omettre la partie fractionnaire des secondes si une précision inférieure à la seconde n'est pas nécessaire ;
• s'assurer que la synchronisation temporelle (NTP) prend en charge la précision requise.

Notes d'implémentation :

Tous les systèmes ne sont pas en mesure de fournir une précision à la microseconde. Il est acceptable de :

• fournir une précision inférieure à 6 chiffres ;
• arrondir ou tronquer à la précision disponible ;
• omettre intégralement TIME-SECFRAC si la précision n'est pas disponible.

A.5. Convention de casse pour les noms (Case Convention for Names)

Le présent document utilise le « lower camel case » pour SD-ID et PARAM-NAME.

Convention :

• la première lettre en minuscule ;
• la première lettre des mots suivants en majuscule ;
• aucun trait d'union ni caractère de soulignement.

Exemples :

• timeQuality
• syncAccuracy
• enterpriseId
• myCompanyName

Avantages :

• cohérence entre les implémentations ;
• lisibilité ;
• compatibilité avec divers langages de programmation.

Recommandation :

Utiliser cette convention pour :

• les nouveaux SD-ID ;
• PARAM-NAME ;
• les identificateurs d'extension.

Les implémentations privées peuvent utiliser d'autres conventions, mais il est recommandé de maintenir la cohérence.

A.6. Applications syslog ne connaissant pas l'heure

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

Quand utiliser NILVALUE pour TIMESTAMP :

• systèmes embarqués ne disposant pas d'horloge temps réel ;
• messages de démarrage émis avant la synchronisation de l'heure ;
• 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 temporelles ;
• lorsqu'une implémentation paresseuse souhaite éviter la gestion de l'heure ;
• lorsque l'heure est disponible mais difficile à obtenir.

Bonnes pratiques :

• émettre un TIMESTAMP valide chaque fois que possible ;
• n'utiliser NILVALUE que lorsque l'heure est véritablement impossible à obtenir ;
• prendre en compte le compromis entre fuseau horaire et précision ;
• documenter la gestion de l'heure dans votre implémentation.

Traitement par les relais :

Un relais recevant des messages avec un TIMESTAMP NILVALUE peut :

• les transférer tels quels ;
• les remplacer par l'heure courante du relais ;
• supprimer les messages (si la politique exige un horodatage).

La configuration doit contrôler ce comportement.

A.7. Notes concernant le SD-ID timeQuality

Le SD-ID timeQuality fournit des métadonnées précieuses sur la précision de l'horodatage.

Paramètre tzKnown :

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

• l'administrateur a configuré explicitement le fuseau horaire ;
• le système d'exploitation fournit des informations de fuseau horaire fiables ;
• le système a validé le fuseau horaire par rapport à une source externe.

Paramètre isSynced :

À définir à 1 uniquement si :

• NTP ou une autre synchronisation temporelle est active ;
• la synchronisation a été vérifiée avec succès ;
• la source temporelle est digne de confiance.

Paramètre syncAccuracy :

À fournir uniquement si :

• la précision réelle est connue (à partir des statistiques NTP) ;
• l'administrateur a configuré la précision attendue ;
• les données mesurées étayent l'affirmation.

Ne pas exagérer la précision :

Une précision factice nuit à la confiance accordée aux journaux. Il vaut mieux :

• omettre intégralement timeQuality si l'on n'est pas certain ;
• fournir une estimation prudente de la précision ;
• documenter les affirmations de précision.

A.8. Encodage UTF-8 et BOM

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

Détails sur le BOM :

• séquence d'octets : 0xEF 0xBB 0xBF ;
• apparaît au début du champ MSG ;
• indique que la suite est encodée en UTF-8.

Quand inclure le BOM :

• lorsque MSG contient du texte encodé en UTF-8 ;
• lorsqu'il existe une certitude quant à l'encodage UTF-8 ;
• pour se conformer à la politique de l'organisation.

Quand omettre le BOM :

• lorsque l'encodage de MSG est inconnu ou incertain ;
• lorsque MSG contient des données binaires ;
• pour la compatibilité ascendante avec les systèmes ne traitant pas le BOM.

Traitement par le récepteur :

Le récepteur doit :

• détecter la présence du BOM ;
• traiter UTF-8 en conséquence ;
• traiter les messages sans BOM (en supposant un encodage inconnu) ;
• ne pas afficher le BOM à l'utilisateur final.

Traitement par les relais :

Un relais transférant des messages doit :

• conserver le BOM s'il est présent ;
• ne pas ajouter de BOM sauf en cas de transcodage vers UTF-8 ;
• ne pas supprimer le BOM sauf en cas de transcodage vers un autre encodage.