Appendice A. Linee guida per gli implementatori

Questa appendice fornisce indicazioni non normative agli implementatori del protocollo syslog.

A.1. Relazione con BSD Syslog

RFC 3164 descriveva il protocollo BSD syslog, distribuito ampiamente per molti anni. Questo documento rende obsoleta RFC 3164, mantenendo tuttavia una significativa compatibilità.

Differenze principali:

• Campo VERSION: questa specifica aggiunge un campo VERSION esplicito, che le implementazioni legacy non riconoscono.
• Formato TIMESTAMP: questa specifica usa timestamp RFC 3339 con data completa, fuso orario e secondi frazionari facoltativi. RFC 3164 usava un formato più semplice, privo di anno e 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 è suddiviso nei campi APP-NAME, PROCID e MSGID dell'HEADER.

Considerazioni di 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 transport sender dovrebbe rilevare le capacità del ricevitore o consentire la configurazione.
• Ricezione da sistemi legacy: i receiver conformi a questa specifica dovrebbero poter analizzare i messaggi RFC 3164 e possono trasformarli nel formato qui definito.
• Comportamento dei relay: i relay possono dover trasformare messaggi tra formati. Nel convertire da questa specifica a RFC 3164:
  • rimuovere il campo VERSION;
  • convertire TIMESTAMP nel formato MMM DD HH:MM:SS;
  • eliminare il fuso orario e l'anno;
  • rimuovere STRUCTURED-DATA o aggiungerlo a MSG;
  • ricostruire TAG da APP-NAME e PROCID.
• Conversione di RFC 3164 in questa specifica:
  • impostare VERSION a 1;
  • aggiungere l'anno corrente al timestamp;
  • usare il fuso orario del relay oppure UTC;
  • analizzare TAG in APP-NAME e PROCID, secondo il miglior sforzo;
  • impostare MSGID a NILVALUE se non determinabile.

A.2. Lunghezza del messaggio

La capacità minima richiesta di 480 ottetti per il receiver ha implicazioni pratiche.

Perché 480 ottetti?

• un singolo pacchetto UDP senza frammentazione in molte reti;
• maggiore probabilità di consegna nelle reti degradate;
• compatibilità con implementazioni limitate.

Implicazioni:

• Messaggi critici: gli avvisi di sicurezza e le emergenze operative dovrebbero rientrare in 480 ottetti;
• Dati per la risoluzione dei problemi: mantenere compatti i messaggi diagnostici;
• Dati importanti per primi: collocare le informazioni critiche all'inizio del messaggio.

Messaggi più grandi:

Molte distribuzioni moderne supportano messaggi molto più grandi:

• il trasporto TLS consente in genere decine o centinaia di kilobyte;
• il trasporto TCP non ha un limite pratico di dimensione;
• le implementazioni moderne supportano spesso messaggi di 2048, 8192 ottetti o più.

Buone pratiche:

• configurare le dimensioni massime in base ai requisiti della distribuzione;
• usare STRUCTURED-DATA per metadati importanti, conteggiati nella lunghezza del messaggio;
• testare le dimensioni massime nel proprio ambiente;
• gestire correttamente i messaggi sovradimensionati, tramite troncamento o rifiuto;
• monitorare i messaggi troncati presso i collector.

Considerazioni su UTF-8:

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

A.3. Valori di Severity

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

Linee guida:

• Emergency (0): usare con parsimonia per emergenze reali.
  • Il sistema è completamente inutilizzabile.
  • È imminente il guasto di hardware critico.
  • È in corso una perdita di dati.
• Alert (1): è richiesta un'azione immediata.
  • Interruzione del servizio.
  • Rilevata violazione della sicurezza.
  • Imminente esaurimento di una risorsa critica.
• Critical (2): condizioni critiche.
  • Guasto del disco rigido.
  • Persa la connessione di rete primaria.
  • Arresto anomalo 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 vicino ai limiti.
  • Uso di funzionalità deprecate.
  • Problemi di configurazione.
• Notice (5): condizione normale ma significativa.
  • Avvio o arresto di servizio.
  • Modifiche di configurazione.
  • Eventi normali rilevanti per la sicurezza.
• Informational (6): messaggi informativi.
  • Operazioni di routine.
  • Messaggi di stato.
  • Instaurazione di connessioni.
• Debug (7): messaggi di livello debug.
  • Informazioni diagnostiche dettagliate.
  • Messaggi destinati agli sviluppatori.
  • Dovrebbero essere disabilitati in produzione.

Considerazioni di configurazione:

Consentire agli amministratori di:

• adattare le assegnazioni Severity alle esigenze della distribuzione;
• filtrare i messaggi per Severity;
• instradare le gravità verso collector diversi;
• sovrascrivere la Severity per tipi di messaggio specifici.

Evitare l'abuso di Severity:

• non contrassegnare tutti i messaggi come Emergency;
• non usare Severity Debug per eventi di produzione;
• considerare l'affaticamento da avvisi degli operatori.

A.4. Precisione di TIME-SECFRAC

Il campo TIMESTAMP supporta secondi frazionari fino a 6 cifre, cioè microsecondi.

Errori comuni:

Omissione degli zeri iniziali:

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

Raccomandazioni di precisione:

• usare millisecondi, 3 cifre, per la maggior parte delle applicazioni;
• usare microsecondi, 6 cifre, per temporizzazioni ad alta precisione;
• omettere i secondi frazionari se non serve precisione sotto il secondo;
• assicurarsi che la sincronizzazione temporale, NTP, supporti la precisione richiesta.

Note di implementazione:

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

• fornire meno di 6 cifre di precisione;
• arrotondare o troncare alla precisione disponibile;
• omettere completamente TIME-SECFRAC se la precisione non è disponibile.

A.5. Convenzione delle maiuscole per i nomi

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

Convenzione:

• prima lettera minuscola;
• iniziale maiuscola per le parole successive;
• nessun trattino né carattere di sottolineatura.

Esempi:

• timeQuality
• syncAccuracy
• enterpriseId
• myCompanyName

Vantaggi:

• coerenza tra le implementazioni;
• leggibilità;
• compatibilità con diversi linguaggi di programmazione.

Raccomandazioni:

Usare questa convenzione per:

• nuovi SD-ID;
• PARAM-NAME;
• identificatori di estensione.

Le implementazioni private possono adottare altre convenzioni, ma la coerenza è raccomandata.

A.6. Applicazioni syslog senza conoscenza dell'ora

La sezione 6.2.3 consente NILVALUE per TIMESTAMP quando l'ora non è nota.

Quando usare NILVALUE per TIMESTAMP:

• sistemi incorporati senza orologio in tempo reale;
• messaggi in fase di avvio prima della sincronizzazione temporale;
• sistemi in cui il recupero dell'ora è fallito.

Quando NON usare NILVALUE:

• quando il sistema operativo fornisce funzioni temporali;
• quando un'implementazione pigra vuole evitare la gestione dell'ora;
• quando l'ora è disponibile ma scomoda da ottenere.

Buone pratiche:

• emettere TIMESTAMP validi ogni volta che sia possibile;
• usare NILVALUE solo se è davvero impossibile ottenere l'ora;
• valutare il compromesso tra fuso orario e precisione;
• documentare la gestione del tempo nell'implementazione.

Gestione dei relay:

I relay che ricevono messaggi con TIMESTAMP NILVALUE possono:

• inoltrarli senza modifiche;
• sostituirlo con l'ora corrente del relay;
• scartare i messaggi, se la policy richiede timestamp.

La configurazione dovrebbe controllare questo comportamento.

A.7. Note sull'SD-ID timeQuality

L'SD-ID timeQuality fornisce metadati utili sulla precisione del timestamp.

Parametro tzKnown:

Il valore predefinito dovrebbe essere 0 (sconosciuto), salvo 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:

Impostarlo a 1 solo quando:

• NTP o altra sincronizzazione temporale è attiva;
• la sincronizzazione è stata verificata con successo;
• la fonte temporale è attendibile.

Parametro syncAccuracy:

Fornirlo solo quando:

• la precisione effettiva è nota, dalle statistiche NTP;
• l'amministratore ha configurato la precisione prevista;
• i dati di misurazione supportano l'affermazione.

Non sovrastimare la precisione:

Una precisione falsa danneggia la fiducia nei log. È preferibile:

• omettere completamente timeQuality se si è incerti;
• fornire stime prudenti della precisione;
• documentare le dichiarazioni di precisione.

A.8. Codifica UTF-8 e BOM

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

Dettagli del BOM:

• sequenza di byte: 0xEF 0xBB 0xBF;
• appare all'inizio del campo MSG;
• indica che segue una codifica UTF-8.

Quando includere il BOM:

• quando MSG contiene testo codificato in UTF-8;
• quando esiste certezza della codifica UTF-8;
• per coerenza con la policy dell'organizzazione.

Quando omettere il BOM:

• quando la codifica di MSG è sconosciuta o incerta;
• quando MSG contiene dati binari;
• per compatibilità con sistemi che non gestiscono il BOM.

Gestione del receiver:

I receiver dovrebbero:

• rilevare la presenza del BOM;
• elaborare di conseguenza UTF-8;
• gestire i messaggi senza BOM assumendo una codifica sconosciuta;
• non visualizzare il BOM agli utenti finali.

Gestione dei relay:

I relay che inoltrano messaggi dovrebbero:

• conservare il BOM se presente;
• non aggiungere il BOM salvo transcodifica in UTF-8;
• non rimuovere il BOM salvo transcodifica in un'altra codifica.