6. Formato dei messaggi syslog

Il messaggio syslog ha la seguente definizione ABNF:

SYSLOG-MSG      = HEADER SP STRUCTURED-DATA [SP MSG]

HEADER          = PRI VERSION SP TIMESTAMP SP HOSTNAME
                  SP APP-NAME SP PROCID SP MSGID
PRI             = "<" PRIVAL ">"
PRIVAL          = 1*3DIGIT ; range 0 .. 191
VERSION         = NONZERO-DIGIT 0*2DIGIT
HOSTNAME        = NILVALUE / 1*255PRINTUSASCII

APP-NAME        = NILVALUE / 1*48PRINTUSASCII
PROCID          = NILVALUE / 1*128PRINTUSASCII
MSGID           = NILVALUE / 1*32PRINTUSASCII

TIMESTAMP       = NILVALUE / FULL-DATE "T" FULL-TIME
FULL-DATE       = DATE-FULLYEAR "-" DATE-MONTH "-" DATE-MDAY
DATE-FULLYEAR   = 4DIGIT
DATE-MONTH      = 2DIGIT  ; 01-12
DATE-MDAY       = 2DIGIT  ; 01-28, 01-29, 01-30, 01-31
FULL-TIME       = PARTIAL-TIME TIME-OFFSET
PARTIAL-TIME    = TIME-HOUR ":" TIME-MINUTE ":" TIME-SECOND
                  [TIME-SECFRAC]
TIME-HOUR       = 2DIGIT  ; 00-23
TIME-MINUTE     = 2DIGIT  ; 00-59
TIME-SECOND     = 2DIGIT  ; 00-59
TIME-SECFRAC    = "." 1*6DIGIT
TIME-OFFSET     = "Z" / TIME-NUMOFFSET
TIME-NUMOFFSET  = ("+" / "-") TIME-HOUR ":" TIME-MINUTE

STRUCTURED-DATA = NILVALUE / 1*SD-ELEMENT
SD-ELEMENT      = "[" SD-ID *(SP SD-PARAM) "]"
SD-PARAM        = PARAM-NAME "=" %d34 PARAM-VALUE %d34
SD-ID           = SD-NAME
PARAM-NAME      = SD-NAME
PARAM-VALUE     = UTF-8-STRING
SD-NAME         = 1*32PRINTUSASCII

MSG             = MSG-ANY / MSG-UTF8
MSG-ANY         = *OCTET
MSG-UTF8        = BOM UTF-8-STRING
BOM             = %xEF.BB.BF
UTF-8-STRING    = *OCTET

OCTET           = %d00-255
SP              = %d32
PRINTUSASCII    = %d33-126
NONZERO-DIGIT   = %d49-57
DIGIT           = %d48 / NONZERO-DIGIT
NILVALUE        = "-"

Il messaggio è composto da:

• HEADER: contiene metadati del messaggio, priorità, versione, timestamp e informazioni sulla sorgente;
• STRUCTURED-DATA: informazioni strutturate facoltative in coppie nome-valore;
• MSG: contenuto facoltativo del messaggio in formato libero.

6.1. Lunghezza del messaggio

I messaggi syslog NON DEVONO superare 480 ottetti nel trasporto UDP. Questo garantisce la compatibilità con implementazioni di rete limitate.

I receiver syslog DEVONO poter accettare messaggi fino a 480 ottetti e DOVREBBERO poter accettare messaggi fino a 2048 ottetti.

I sender syslog POSSONO inviare messaggi più lunghi di 480 ottetti; tuttavia, se necessario, DOVREBBERO implementare meccanismi di troncamento o suddivisione.

Le mappature di trasporto POSSONO specificare dimensioni massime differenti. Per esempio, il trasporto TLS consente in genere messaggi molto più grandi.

La lunghezza del messaggio è misurata in ottetti, non in caratteri. La codifica UTF-8 può richiedere più ottetti per carattere.

6.2. HEADER

L'HEADER contiene i seguenti campi nell'esatto ordine indicato:

6.2.1. PRI

La parte PRI contiene il valore Priority racchiuso tra parentesi angolari. Priority è calcolato a partire dai valori Facility e Severity:

Priority = Facility * 8 + Severity

Valori Facility:

Valore	Facility
0	messaggi del kernel
1	messaggi a livello utente
2	sistema di posta
3	demoni di sistema
4	messaggi di sicurezza/autorizzazione
5	messaggi generati internamente da syslogd
6	sottosistema stampante di linea
7	sottosistema network news
8	sottosistema UUCP
9	demone dell'orologio
10	messaggi di sicurezza/autorizzazione
11	demone FTP
12	sottosistema NTP
13	audit dei log
14	avviso dei log
15	demone dell'orologio
16-23	uso locale 0-7, local0 - local7

Valori Severity:

Valore	Severity	Descrizione
0	Emergency	il sistema è inutilizzabile
1	Alert	è necessaria un'azione immediata
2	Critical	condizioni critiche
3	Error	condizioni di errore
4	Warning	condizioni di avviso
5	Notice	condizione normale ma significativa
6	Informational	messaggi informativi
7	Debug	messaggi di livello debug

Esempio: un messaggio con Facility 4, sicurezza/autorizzazione, e Severity 2, Critical, ha il seguente valore Priority:

Priority = 4 * 8 + 2 = 34
PRI = "<34>"

Il valore PRI DEVE essere compreso tra 0 e 191.

6.2.2. VERSION

Il campo VERSION indica la versione del protocollo syslog. Questo documento definisce la versione 1. VERSION DEVE essere un intero diverso da zero nell'intervallo 1-999.

6.2.3. TIMESTAMP

Il campo TIMESTAMP è un timestamp formattato che indica quando è stato generato il messaggio. DOVREBBE rappresentare l'ora in cui si è verificato l'evento descritto.

Il formato del timestamp si basa su RFC 3339 e richiede:

• data nel formato YYYY-MM-DD;
• separatore dell'ora "T";
• ora nel formato HH:MM:SS, 24 ore;
• secondi frazionari facoltativi, fino a 6 cifre;
• offset di fuso orario, "Z" per UTC o "+/-HH:MM".

Esempi:

2003-10-11T22:14:15.003Z
2003-08-24T05:14:15.000003-07:00
2009-03-12T18:53:01+00:00

Se l'originator non conosce l'ora, DEVE usare NILVALUE ("-").

Buone pratiche:

• usare il fuso UTC, Z, quando possibile, per coerenza;
• includere i secondi frazionari quando la precisione è importante;
• garantire la sincronizzazione dell'ora, NTP, per timestamp accurati.

6.2.4. HOSTNAME

Il campo HOSTNAME identifica la macchina che ha originariamente generato il messaggio syslog. DOVREBBE contenere uno dei seguenti valori:

1. Fully Qualified Domain Name (FQDN), RACCOMANDATO;
2. indirizzo IP statico;
3. nome host;
4. indirizzo IP dinamico;
5. NILVALUE ("-") se sconosciuto.

FQDN è il formato RACCOMANDATO perché fornisce l'identificazione più accurata.

Se è usato un indirizzo IPv6, DOVREBBE essere racchiuso tra parentesi quadre.

Lunghezza massima: 255 caratteri ASCII stampabili.

6.2.5. APP-NAME

Il campo APP-NAME identifica il dispositivo o l'applicazione che ha generato il messaggio. È una stringa in formato libero senza spazi.

Esempi:

myapp
su
postfix/smtpd

Lunghezza massima: 48 caratteri ASCII stampabili.

Se APP-NAME è sconosciuto, usare NILVALUE ("-").

6.2.6. PROCID

Il campo PROCID è un valore che cambia ogni volta che un processo viene avviato o riavviato. Di norma contiene:

• l'identificatore di processo (PID) nei sistemi Unix-like;
• l'identificatore del thread;
• il nome del processo;
• un altro identificatore univoco.

Esempi:

12345
thread1
-

Lunghezza massima: 128 caratteri ASCII stampabili.

Se PROCID non è usato, impostarlo a NILVALUE ("-").

6.2.7. MSGID

Il campo MSGID identifica il tipo di messaggio. È una stringa in formato libero senza spazi, utilizzabile per l'analisi e l'instradamento automatici.

Esempi:

ID47
TCPIN
login-failure
config-change

Lunghezza massima: 32 caratteri ASCII stampabili.

Se MSGID non è usato, impostarlo a NILVALUE ("-").

6.3. STRUCTURED-DATA

STRUCTURED-DATA fornisce un meccanismo per esprimere informazioni in un formato strutturato e facilmente analizzabile. È composto da uno o più SD-ELEMENT.

6.3.1. SD-ELEMENT

Un SD-ELEMENT è composto da:

• SD-ID, identificatore;
• zero o più SD-PARAM, parametri.

Formato: [SD-ID PARAM1="value1" PARAM2="value2" ...]

6.3.2. SD-ID

Lo SD-ID identifica univocamente il tipo e lo scopo dell'elemento.

SD-ID registrati IANA: consistono di caratteri ASCII stampabili, esclusi =, ], " e lo spazio.

SD-ID di impresa privata: DEVONO avere il formato name@<private enterprise number>, dove il numero d'impresa è registrato presso IANA.

Esempi:

timeQuality
origin
myCompany@32473

6.3.3. SD-PARAM

Ogni SD-PARAM è una coppia nome-valore:

PARAM-NAME="PARAM-VALUE"

PARAM-VALUE DEVE essere codificato in UTF-8. I caratteri speciali devono essere sottoposti a escape:

• " becomes \"
• \ becomes \\
• ] becomes \]

Esempio:

[exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"]

Valori multipli per lo stesso nome di parametro sono consentiti ripetendo il parametro:

[example ip="192.0.2.1" ip="192.0.2.2"]

6.3.4. Controllo delle modifiche

Nuovi SD-ID possono essere registrati tramite IANA. Per i dettagli si veda la sezione 9.

Le imprese private possono usare il proprio numero d'impresa registrato per creare SD-ID privati senza ulteriore registrazione.

6.3.5. Esempi

Singolo SD-ELEMENT:

[exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"]

SD-ELEMENT multipli:

[exampleSDID@32473 iut="3"][examplePriority@32473 class="high"]

Nessun dato strutturato:

-

6.4. MSG

La parte MSG contiene il testo libero del messaggio. Ha due formati possibili:

1. MSG-ANY: qualsiasi sequenza di ottetti;
2. MSG-UTF8: stringa UTF-8 con prefisso BOM (Byte Order Mark: 0xEF 0xBB 0xBF).

Se MSG inizia con il BOM UTF-8, il collector o relay DOVREBBE presumere che MSG sia codificato in UTF-8. Altrimenti, la codifica non è specificata.

La parte MSG è facoltativa. Se assente, nessuno SP precede la fine del messaggio.

Buone pratiche:

• usare la codifica UTF-8 con BOM per un supporto coerente dei caratteri internazionali;
• evitare di includere newline o altri caratteri di controllo;
• mantenere le informazioni importanti all'inizio del messaggio, entro i primi 480 ottetti.

6.5. Esempi

Esempio 1: messaggio completo con tutti i campi e dati strutturati

<34>1 2003-10-11T22:14:15.003Z mymachine.example.com su - ID47 [exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"] BOMsystem crashed

Esempio 2: messaggio con campi NILVALUE

<165>1 2003-08-24T05:14:15.000003-07:00 192.0.2.1 myproc 8710 - - %% It's time to make the do-nuts.

Esempio 3: messaggio con contenuto UTF-8 e SD-ELEMENT multipli

<165>1 2003-10-11T22:14:15.003Z mymachine.example.com evntslog - ID47 [exampleSDID@32473 iut="3" eventSource="Application" eventID="1011"][examplePriority@32473 class="high"] BOMAn application event log entry...

Esempio 4: messaggio minimo, messaggio Emergency del kernel

<0>1 2009-03-12T18:53:01+00:00 server1 kernel - - - System will shutdown