Anhang A. Richtlinien für Implementierer (Implementer Guidelines)

Dieser Anhang bietet nicht-normative Anleitungen für Implementierer des Syslog-Protokolls.

A.1. Beziehung zu BSD Syslog

RFC 3164 beschrieb das BSD-Syslog-Protokoll, das seit vielen Jahren weit verbreitet ist. Dieses Dokument macht RFC 3164 obsolet, behält jedoch erhebliche Kompatibilität bei.

Hauptunterschiede:

• VERSION-Feld: Diese Spezifikation fügt ein explizites VERSION-Feld hinzu. Legacy-Implementierungen werden dieses Feld nicht erkennen.

• TIMESTAMP-Format: Diese Spezifikation verwendet RFC 3339-Zeitstempel mit vollständigem Datum, Zeitzone und optionalen Sekundenbruchteilen. RFC 3164 verwendete ein einfacheres Format ohne Jahr oder Zeitzone.

• STRUCTURED-DATA: Diese Spezifikation führt strukturierte Datenelemente ein. RFC 3164 hatte keinen entsprechenden Mechanismus.

• MSG-Format: Das TAG-Feld aus RFC 3164 wurde im HEADER in APP-NAME-, PROCID- und MSGID-Felder aufgeteilt.

Interoperabilitätsüberlegungen:

Bei der Kommunikation mit RFC 3164-Systemen:

• Senden an Legacy-Systeme: Formatieren Sie Nachrichten gemäß RFC 3164, wenn der Empfänger diese Spezifikation nicht unterstützt. Der Transportsender sollte Empfängerfähigkeiten erkennen oder eine Konfiguration ermöglichen.

• Empfangen von Legacy-Systemen: Empfänger, die mit dieser Spezifikation konform sind, sollten in der Lage sein, RFC 3164-Nachrichten zu analysieren. Der Empfänger kann sie in das in diesem Dokument definierte Format umwandeln.

• Relay-Verhalten: Relays müssen möglicherweise Nachrichten zwischen Formaten transformieren. Bei der Konvertierung von dieser Spezifikation zu RFC 3164:

  • VERSION-Feld entfernen
  • TIMESTAMP in MMM DD HH:MM:SS-Format konvertieren
  • Zeitzone und Jahresinformationen verwerfen
  • STRUCTURED-DATA entfernen oder an MSG anhängen
  • TAG aus APP-NAME und PROCID rekonstruieren

• Konvertierung von RFC 3164 zu dieser Spezifikation:

  • VERSION auf 1 setzen
  • Aktuelles Jahr zum Zeitstempel hinzufügen
  • Zeitzone des Relays oder UTC verwenden
  • TAG in APP-NAME und PROCID parsen (Best Effort)
  • MSGID auf NILVALUE setzen, falls nicht bestimmbar

A.2. Nachrichtenlänge

Die minimal erforderliche Empfängerkapazität von 480 Oktetten hat praktische Auswirkungen:

Warum 480 Oktette?

• Einzelnes UDP-Paket ohne Fragmentierung in vielen Netzwerken
• Höhere Zustellwahrscheinlichkeit in degradierten Netzwerken
• Kompatibilität mit begrenzten Implementierungen

Auswirkungen:

• Kritische Nachrichten: Sicherheitswarnungen und betriebliche Notfälle sollten in 480 Oktette passen
• Diagnosedaten: Diagnosenachrichten kompakt halten
• Wichtige Daten zuerst: Kritische Informationen früh in der Nachricht platzieren

Größere Nachrichten:

Viele moderne Bereitstellungen unterstützen viel größere Nachrichten:

• TLS-Transport erlaubt typischerweise Zehner oder Hunderter von Kilobytes
• TCP-Transport hat keine praktische Größenbeschränkung
• Moderne Implementierungen unterstützen oft 2048, 8192 oder größere Nachrichten

Best Practices:

• Maximale Nachrichtengrößen basierend auf Bereitstellungsanforderungen konfigurieren
• STRUCTURED-DATA für wichtige Metadaten verwenden (in Nachrichtenlänge eingerechnet)
• Maximale Nachrichtengrößen in Ihrer Umgebung testen
• Würdevolle Behandlung überdimensionierter Nachrichten implementieren (Kürzung oder Ablehnung)
• Bei Collectors auf gekürzte Nachrichten überwachen

UTF-8-Überlegungen:

Die Nachrichtenlänge wird in Oktetten gemessen, nicht in Zeichen. Eine 1000-Zeichen-UTF-8-Zeichenkette kann 3000 oder mehr Oktette sein, wenn sie Nicht-ASCII-Zeichen enthält. Implementierer müssen dies beim Dimensionieren von Nachrichten berücksichtigen.

A.3. Severity-Werte

Die ordnungsgemäße Verwendung von Severity-Werten verbessert den Nutzen der Nachricht.

Richtlinien:

• Emergency (0): Sparsam für echte Notfälle verwenden

  • System ist völlig unbenutzbar
  • Unmittelbar bevorstehender Ausfall kritischer Hardware
  • Datenverlust tritt auf

• Alert (1): Sofortiges Handeln erforderlich

  • Dienstausfall
  • Sicherheitsverletzung erkannt
  • Erschöpfung kritischer Ressourcen unmittelbar bevorstehend

• Critical (2): Kritische Bedingungen

  • Festplattenausfall
  • Primäre Netzwerkverbindung verloren
  • Anwendungsabstürze

• Error (3): Fehlerbedingungen

  • Nicht-kritische Dienstausfälle
  • Wiederherstellbare Fehler
  • Verbindungs-Timeouts

• Warning (4): Warnungsbedingungen

  • Ressourcennutzung nähert sich Grenzen
  • Verwendung veralteter Funktionen
  • Konfigurationsprobleme

• Notice (5): Normal aber bedeutsam

  • Dienststart/-stopp
  • Konfigurationsänderungen
  • Sicherheitsrelevante normale Ereignisse

• Informational (6): Informationsnachrichten

  • Routineoperationen
  • Statusmeldungen
  • Verbindungsaufbau

• Debug (7): Debug-Level-Nachrichten

  • Detaillierte Diagnoseinformationen
  • Entwicklerorientierte Nachrichten
  • Sollte in der Produktion deaktiviert sein

Konfigurationsüberlegungen:

Administratoren erlauben:

• Severity-Zuweisungen pro Bereitstellungsbedarf anpassen
• Nachrichten nach Severity filtern
• Severities an verschiedene Collectors weiterleiten
• Severity für bestimmte Nachrichtentypen überschreiben

Severity-Missbrauch vermeiden:

• Nicht alle Nachrichten als Emergency markieren
• Nicht Debug-Severity für Produktionsereignisse verwenden
• Operator-Alert-Fatigue berücksichtigen

A.4. TIME-SECFRAC-Präzision

Das TIMESTAMP-Feld unterstützt Sekundenbruchteile bis zu 6 Ziffern (Mikrosekunden).

Häufige Fehler:

Führende Nullen weglassen:

FALSCH: 2003-10-11T22:13:14.3      (erscheint als 300ms)
RICHTIG: 2003-10-11T22:13:14.003    (tatsächlich 3ms)

Präzisionsempfehlungen:

• Millisekunden (3 Ziffern) für die meisten Anwendungen verwenden
• Mikrosekunden (6 Ziffern) für hochpräzises Timing verwenden
• Sekundenbruchteile weglassen, wenn Sub-Sekunden-Präzision nicht benötigt wird
• Sicherstellen, dass die Zeitsynchronisation (NTP) die erforderliche Präzision unterstützt

Implementierungshinweise:

Nicht alle Systeme können Mikrosekunden-Präzision bieten. Es ist akzeptabel:

• Weniger Präzision als 6 Ziffern bereitzustellen
• Auf verfügbare Präzision zu runden oder zu kürzen
• TIME-SECFRAC vollständig wegzulassen, wenn Präzision nicht verfügbar ist

A.5. Namenskonvention

Dieses Dokument verwendet "lower camel case" für SD-IDs und PARAM-NAMEs.

Konvention:

• Erster Buchstabe klein
• Erste Buchstaben nachfolgender Wörter groß
• Keine Bindestriche oder Unterstriche

Beispiele:

• timeQuality
• syncAccuracy
• enterpriseId
• myCompanyName

Vorteile:

• Konsistenz über Implementierungen hinweg
• Lesbarkeit
• Kompatibilität mit verschiedenen Programmiersprachen

Empfehlungen:

Diese Konvention verwenden für:

• Neue SD-IDs
• PARAM-NAMEs
• Erweiterungskennungen

Private Implementierungen können andere Konventionen verwenden, aber Konsistenz wird empfohlen.

A.6. Syslog-Anwendungen ohne Zeitkenntnis

Abschnitt 6.2.3 erlaubt NILVALUE für TIMESTAMP, wenn die Zeit unbekannt ist.

Wann NILVALUE für TIMESTAMP verwenden:

• Eingebettete Systeme ohne Echtzeituhr
• Boot-Zeit-Nachrichten vor Zeitsynchronisation
• Systeme, bei denen Zeitabruf fehlgeschlagen ist

Wann NICHT NILVALUE verwenden:

• Wenn das Betriebssystem Zeitfunktionen bereitstellt
• Wenn faule Implementierung Zeitbehandlung vermeiden will
• Wenn Zeit verfügbar, aber unbequem zu erhalten ist

Best Practices:

• Wann immer möglich gültige TIMESTAMPs ausgeben
• NILVALUE nur verwenden, wenn es wirklich unmöglich ist, Zeit zu erhalten
• Zeitzone vs. Genauigkeits-Trade-offs berücksichtigen
• Zeitbehandlung in Ihrer Implementierung dokumentieren

Relay-Behandlung:

Relays, die Nachrichten mit NILVALUE TIMESTAMP empfangen, können:

• Unverändert weiterleiten
• Mit aktueller Zeit des Relays ersetzen
• Nachrichten verwerfen (wenn Richtlinie Zeitstempel erfordert)

Die Konfiguration sollte dieses Verhalten steuern.

A.7. Hinweise zur timeQuality SD-ID

Die timeQuality SD-ID bietet wertvolle Metadaten über Zeitstempel-Genauigkeit.

tzKnown-Parameter:

Standard sollte 0 (unbekannt) sein, es sei denn:

• Administrator hat Zeitzone explizit konfiguriert
• Betriebssystem bietet zuverlässige Zeitzoneninfo
• System hat Zeitzone gegen externe Quelle validiert

isSynced-Parameter:

Nur auf 1 setzen, wenn:

• NTP oder andere Zeitsynchronisation aktiv ist
• Synchronisation erfolgreich verifiziert ist
• Zeitquelle vertrauenswürdig ist

syncAccuracy-Parameter:

Nur bereitstellen, wenn:

• Tatsächliche Genauigkeit bekannt ist (aus NTP-Statistiken)
• Administrator erwartete Genauigkeit konfiguriert hat
• Messdaten den Anspruch unterstützen

Genauigkeit nicht übertreiben:

Falsche Präzision schadet dem Vertrauen in Logs. Es ist besser:

• timeQuality ganz wegzulassen, wenn unsicher
• Konservative Genauigkeitsschätzungen bereitzustellen
• Genauigkeitsansprüche zu dokumentieren

A.8. UTF-8-Kodierung und das BOM

Das BOM (Byte Order Mark) signalisiert UTF-8-Kodierung im MSG-Feld.

BOM-Details:

• Byte-Sequenz: 0xEF 0xBB 0xBF
• Erscheint am Anfang des MSG-Feldes
• Zeigt an, dass UTF-8-Kodierung folgt

Wann BOM einschließen:

• Wenn MSG UTF-8-kodierten Text enthält
• Wenn Gewissheit über UTF-8-Kodierung besteht
• Für Konsistenz mit Organisationsrichtlinien

Wann BOM weglassen:

• Wenn MSG-Kodierung unbekannt oder unsicher ist
• Wenn MSG binäre Daten enthält
• Für Abwärtskompatibilität mit Systemen, die BOM nicht behandeln

Empfänger-Behandlung:

Empfänger sollten:

• BOM-Präsenz erkennen
• UTF-8 entsprechend verarbeiten
• Nachrichten ohne BOM behandeln (unbekannte Kodierung annehmen)
• BOM nicht an Endbenutzer anzeigen

Relay-Behandlung:

Relays, die Nachrichten weiterleiten, sollten:

• BOM beibehalten, falls vorhanden
• BOM nicht hinzufügen, es sei denn, es wird zu UTF-8 transkodiert
• BOM nicht entfernen, es sei denn, es wird zu einer anderen Kodierung transkodiert