Appendice A. Linee guida per gli implementatori (Implementer Guidelines)

Questa appendice fornisce indicazioni non normative per gli implementatori del protocollo syslog.

A.1. Relazione con BSD Syslog

RFC 3164 descriveva il protocollo BSD syslog, ampiamente utilizzato per molti anni. Questo documento sostituisce RFC 3164 mantenendo una significativa compatibilità.

Differenze principali:

• Campo VERSION: Questa specifica aggiunge un campo VERSION esplicito. Le implementazioni legacy non riconosceranno questo campo.

• Formato TIMESTAMP: Questa specifica utilizza timestamp RFC 3339 con data completa, fuso orario e secondi frazionari opzionali. RFC 3164 utilizzava un formato più semplice senza anno o fuso orario.

• STRUCTURED-DATA: Questa specifica introduce elementi di dati strutturati. RFC 3164 non aveva un meccanismo equivalente.

• Formato MSG: Il campo TAG di RFC 3164 è stato suddiviso nei campi APP-NAME, PROCID e MSGID nell'HEADER.

Considerazioni sull'interoperabilità:

Quando si comunica con sistemi RFC 3164:

• Invio a sistemi legacy: Formattare i messaggi secondo RFC 3164 se il ricevitore non supporta questa specifica. Il mittente del trasporto dovrebbe rilevare le capacità del ricevitore o consentire la configurazione.

• Ricezione da sistemi legacy: I ricevitori conformi a questa specifica dovrebbero essere in grado di analizzare i messaggi RFC 3164. Il ricevitore può trasformarli nel formato definito in questo documento.

• Comportamento relay: I relay potrebbero dover trasformare i messaggi tra i formati. Quando si converte da questa specifica a RFC 3164:

  • Rimuovere il campo VERSION
  • Convertire TIMESTAMP nel formato MMM DD HH:MM:SS
  • Eliminare informazioni sul fuso orario e l'anno
  • Rimuovere STRUCTURED-DATA o aggiungerlo a MSG
  • Ricostruire TAG da APP-NAME e PROCID

• Conversione da RFC 3164 a questa specifica:

  • Impostare VERSION a 1
  • Aggiungere l'anno corrente al timestamp
  • Utilizzare il fuso orario del relay o UTC
  • Analizzare TAG in APP-NAME e PROCID (best effort)
  • Impostare MSGID a NILVALUE se non determinabile

A.2. Lunghezza del messaggio (Message Length)

La capacità minima richiesta del ricevitore di 480 ottetti ha implicazioni pratiche:

Perché 480 ottetti?

• Singolo pacchetto UDP senza frammentazione su molte reti
• Maggiore probabilità di consegna in reti degradate
• Compatibilità con implementazioni limitate

Implicazioni:

• Messaggi critici: Avvisi di sicurezza ed emergenze operative dovrebbero rientrare in 480 ottetti
• Dati di troubleshooting: Mantenere compatti i messaggi diagnostici
• Dati importanti prima: Posizionare le informazioni critiche all'inizio del messaggio

Messaggi più grandi:

Molte distribuzioni moderne supportano messaggi molto più grandi:

• Il trasporto TLS consente tipicamente decine o centinaia di kilobyte
• Il trasporto TCP non ha limiti di dimensione pratici
• Le implementazioni moderne spesso supportano messaggi da 2048, 8192 o più grandi

Best practices:

• Configurare le dimensioni massime dei messaggi in base ai requisiti di distribuzione
• Utilizzare STRUCTURED-DATA per metadati importanti (contati nella lunghezza del messaggio)
• Testare le dimensioni massime dei messaggi nel proprio ambiente
• Implementare una gestione elegante dei messaggi sovradimensionati (troncamento o rifiuto)
• Monitorare i messaggi troncati nei collector

Considerazioni UTF-8:

La lunghezza del messaggio è misurata in ottetti, non in caratteri. Una stringa UTF-8 di 1000 caratteri può essere di 3000 o più ottetti se contiene caratteri non ASCII. Gli implementatori devono tenerne conto quando dimensionano i messaggi.

A.3. Valori di gravità (Severity Values)

L'uso corretto dei valori di gravità migliora l'utilità dei messaggi.

Linee guida:

• Emergency (0): Utilizzare con parsimonia per vere emergenze

  • Il sistema è completamente inutilizzabile
  • Imminente guasto dell'hardware critico
  • Perdita di dati in corso

• Alert (1): Azione immediata richiesta

  • Interruzione del servizio
  • Violazione della sicurezza rilevata
  • Esaurimento imminente delle risorse critiche

• Critical (2): Condizioni critiche

  • Guasto del disco rigido
  • Connessione di rete primaria persa
  • Crash dell'applicazione

• Error (3): Condizioni di errore

  • Guasti di servizi non critici
  • Errori recuperabili
  • Timeout di connessione

• Warning (4): Condizioni di avviso

  • Utilizzo delle risorse che si avvicina ai limiti
  • Uso di funzionalità deprecate
  • Problemi di configurazione

• Notice (5): Normale ma significativo

  • Avvio/arresto del servizio
  • Modifiche alla configurazione
  • Eventi normali rilevanti per la sicurezza

• Informational (6): Messaggi informativi

  • Operazioni di routine
  • Messaggi di stato
  • Stabilimento della connessione

• Debug (7): Messaggi a livello di debug

  • Informazioni diagnostiche dettagliate
  • Messaggi orientati allo sviluppatore
  • Dovrebbero essere disabilitati in produzione

Considerazioni sulla configurazione:

Consentire agli amministratori di:

• Regolare le assegnazioni di gravità per esigenze di distribuzione
• Filtrare i messaggi per gravità
• Instradare le gravità a diversi collector
• Sovrascrivere la gravità per tipi di messaggio specifici

Evitare l'abuso della gravità:

• Non contrassegnare tutti i messaggi come Emergency
• Non utilizzare la gravità Debug per eventi di produzione
• Considerare l'affaticamento da avvisi dell'operatore

A.4. Precisione TIME-SECFRAC

Il campo TIMESTAMP supporta secondi frazionari fino a 6 cifre (microsecondi).

Errori comuni:

Eliminare gli zeri iniziali:

SBAGLIATO: 2003-10-11T22:13:14.3      (sembra 300ms)
CORRETTO: 2003-10-11T22:13:14.003    (in realtà 3ms)

Raccomandazioni sulla precisione:

• Utilizzare millisecondi (3 cifre) per la maggior parte delle applicazioni
• Utilizzare microsecondi (6 cifre) per temporizzazioni ad alta precisione
• Omettere i secondi frazionari se la precisione sub-secondo non è necessaria
• Garantire che la sincronizzazione temporale (NTP) supporti la precisione richiesta

Note di implementazione:

Non tutti i sistemi possono fornire precisione al microsecondo. È accettabile:

• Fornire precisione inferiore a 6 cifre
• Arrotondare o troncare alla precisione disponibile
• Omettere completamente TIME-SECFRAC se la precisione non è disponibile

A.5. Convenzione del caso per i nomi (Case Convention for Names)

Questo documento utilizza "lower camel case" per SD-ID e PARAM-NAME.

Convenzione:

• Prima lettera minuscola
• Prime lettere delle parole successive maiuscole
• Nessun trattino o underscore

Esempi:

• timeQuality
• syncAccuracy
• enterpriseId
• myCompanyName

Vantaggi:

• Coerenza tra le implementazioni
• Leggibilità
• Compatibilità con vari linguaggi di programmazione

Raccomandazioni:

Utilizzare questa convenzione per:

• Nuovi SD-ID
• PARAM-NAME
• Identificatori di estensione

Le implementazioni private possono utilizzare altre convenzioni ma si raccomanda la coerenza.

A.6. Applicazioni Syslog senza conoscenza del tempo

La sezione 6.2.3 consente NILVALUE per TIMESTAMP quando il tempo è sconosciuto.

Quando utilizzare NILVALUE per TIMESTAMP:

• Sistemi embedded senza orologi in tempo reale
• Messaggi all'avvio prima della sincronizzazione temporale
• Sistemi in cui il recupero del tempo è fallito

Quando NON utilizzare NILVALUE:

• Quando il sistema operativo fornisce funzioni di tempo
• Quando un'implementazione pigra vuole evitare la gestione del tempo
• Quando il tempo è disponibile ma scomodo da ottenere

Best practices:

• Emettere TIMESTAMP validi quando possibile
• Utilizzare NILVALUE solo quando è veramente impossibile ottenere il tempo
• Considerare i compromessi tra fuso orario e accuratezza
• Documentare la gestione del tempo nella propria implementazione

Gestione relay:

I relay che ricevono messaggi con TIMESTAMP NILVALUE possono:

• Inoltrare così com'è
• Sostituire con il tempo corrente del relay
• Eliminare i messaggi (se la politica richiede timestamp)

La configurazione dovrebbe controllare questo comportamento.

A.7. Note sull'SD-ID timeQuality

L'SD-ID timeQuality fornisce metadati preziosi sull'accuratezza del timestamp.

Parametro tzKnown:

Il valore predefinito dovrebbe essere 0 (sconosciuto) a meno che:

• L'amministratore abbia configurato esplicitamente il fuso orario
• Il sistema operativo fornisca informazioni affidabili sul fuso orario
• Il sistema abbia convalidato il fuso orario rispetto a una fonte esterna

Parametro isSynced:

Impostare a 1 solo quando:

• NTP o altra sincronizzazione temporale è attiva
• La sincronizzazione è verificata con successo
• La fonte di tempo è affidabile

Parametro syncAccuracy:

Fornire solo quando:

• L'accuratezza effettiva è nota (dalle statistiche NTP)
• L'amministratore ha configurato l'accuratezza prevista
• I dati di misurazione supportano l'affermazione

Non sovrastimare l'accuratezza:

La falsa precisione danneggia la fiducia nei log. È meglio:

• Omettere completamente timeQuality se incerti
• Fornire stime di accuratezza conservative
• Documentare le affermazioni di accuratezza

A.8. Codifica UTF-8 e BOM

Il BOM (Byte Order Mark) segnala la codifica UTF-8 nel campo MSG.

Dettagli BOM:

• Sequenza di byte: 0xEF 0xBB 0xBF
• Appare all'inizio del campo MSG
• Indica che segue la codifica UTF-8

Quando includere BOM:

• Quando MSG contiene testo codificato UTF-8
• Quando esiste certezza della codifica UTF-8
• Per coerenza con la politica organizzativa

Quando omettere BOM:

• Quando la codifica MSG è sconosciuta o incerta
• Quando MSG contiene dati binari
• Per compatibilità con sistemi che non gestiscono BOM

Gestione ricevitore:

I ricevitori dovrebbero:

• Rilevare la presenza di BOM
• Elaborare UTF-8 di conseguenza
• Gestire messaggi senza BOM (assumere codifica sconosciuta)
• Non visualizzare BOM agli utenti finali

Gestione relay:

I relay che inoltrano messaggi dovrebbero:

• Preservare BOM se presente
• Non aggiungere BOM a meno che non si transcodifichi in UTF-8
• Non rimuovere BOM a meno che non si transcodifichi in un'altra codifica