# LogDoctor - Aiuto

# Apache2

##
Stringa di formato per i log di accesso

###
File di configurazione

Il file di configurazione è generalmente:

`/etc/apache2/apache2.conf`

La linea usata per configurare i log di accesso è quella che inizia con "LogFormat" seguita dalla lista dei codici dei campi.

### Formati comuni

I formati più comunemente usati sono:

- Common log format (CLF)
`LogFormat "%h %l %u %t \"%r\" %>s %O" common`
- Combined log format (NCSA standard)
`LogFormat "%h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-agent}i\"" combined`

### Formati suggeriti

La stringa di formato suggerita, per usare a pieno le funzionalità di LogDoctor, è:

`LogFormat "%{%F %T}t %H %m %U %q %>s %I %O %D \"%{Referer}i\" \"%{Cookie}i\" \"%{User-agent}i\" %{c}h" combined`

È preferibile usare la stringa precedente, ma possono essere usate anche delle alternative, come:

`LogFormat "%{sec}t \"%r\" %q %<s %I %O %D \"%{Referer}i\" \"%{Cookie}i\" \"%{User-agent}i\" %h" combined`

### Nota sulle stringhe personalizzate

Se stai usando una stringa personalizzata, tieni a mente che l'analisi dei log non é una magia. Quando definisci la tua stringa, pensa a quali caratteri possono essere contenuti in un determinato campo e scegli dei separatori adeguati che non entrino in conflitto con il campo stesso.
Ad esempio: un URI (%U) non può contenere spazi, quindi non è un problema usare uno spazio per separarlo dal campo successivo. Al contrario invece, lo User-Agent (*%{User-agent}i*) potrebbe contenere spazei, parentesi di vario tipo, trattini, ecc, quindi è necessario scegliere un separatoe adeguato (le virgolette sono una buona scelta, dato che in fase di log vengono fatte precedere da un backslash).

### Nota sui caratteri di controllo

Nonostante Apache2 supporti l'uso di alcuni caratteri di controllo (a.k.a. sequenze di escape), la raccomandazione è di non usarli nella stringa di formato.
In particolare, il carriage return potrebbe causare una sovrascrittura dei dati dei campi precedenti, rendendo molto difficile capire dove inizia il campo corrente (specialmente per campi come URI, query, user-agent, ecc) e praticamente impossibile il recupero dei dati sovrascritti, cosa che porta ad avere un database errato, statistiche non realistiche e/o crash durante l'esecuzione.
In riferimento al carattere new line (a.k.a. a capo), non ha praticamente senso usarlo, se non per propositi di test. La stessa cosa vale per il tab orizzontale, al posto del quale è più opportuno usare un singolo spazio.
I caratteri di controllo supportati da Apache2 sono \n, \t e \r. Gli altri caratteri cerranno ignorati ed usati come testo.

##
Campi dei log di accesso

###
Campi considerati da LogDoctor

Gli unici campi considerati sono quelli che seguono, ovvero solo i dati di questi campi verranno salvati nel database ed usati per le statistiche.

Codice | Informazioni
--- | ---
%% | Il simbolo di percentuale, risulterà in un singolo simbolo e verrà trattato come testo (sia da Apache che da LogDoctor).
%t | Il momento di arrivo della richiesta, nel formato [GG/Mes/AAAA:oo:mm:ss ±FO]. L'ultimo valore (FO) indica la differenza di fusorario da Greenwich.

%{FORMATO}t

Il momento di arrivo della richiesta, in una forma specificata da FORMATO, il quale dovrebbe essere uno dei formati estesi di strftime.
I seguenti codici di formato sono supportati (da LogDoctor, tutti gli altri verranno scartati, anche se validi):

Formato | Descrizione
--- | ---
sec | tempo Unix, in secondi
msec | tempo Unix, in millisecondi
usec | tempo Unix, in microsecondi
%b | nome del mese, abbreviato (come %h)
%B | nome del mese
%c | rappresentazione di data e orario
%d | numero del giorno, con zero
%D | data, nel formato MM/GG/AA
%e | numero del giorno, senza zero
%F | data, nel formato AAAA/MM/GG
%h | nome del mese, abbreviato (come %b)
%H | ora, con rappresentazione in 24h, con zero
%m | numero del mese, con zero
%M | minuto
%r | orario del giorno, con rappresentazione in 12h, nel formato OO:MM:SS AM/PM
%R | orario del giorno, nel formato OO:MM
%S | secondo
%T | orario ISO 8601, nel formato OO:MM:SS
%x | rappresentazione della data
%X | rappresentazione dell'orario
%y | anno, ultime due cifre (AA)
%Y | anno

Nota: i formati sec, msec e usec non possono essere usanti assieme ad altri formati.

%r | Prima linea della richiesta, equivalente a: %m %U?%q %H.
%H | Il protocollo della richiesta (HTTP/v, HTTPS/v).
%m | Il metodo della richiesta (GET, POST, HEAD, ...).
%U | L'URI richiesto, senza la stringa di query.
%q | La stringa di query (se presente).
%s | Codice iniziale dello Status HTTP per richiesta (esclude gli status di eventuali redirezioni).
%>s | Codice finale dello Status HTTP per richiesta (nel caso in cui la richiesta abbia subito redirezioni interne).
%I | Numero di Byte recevuti, inclusi la richiesta e gli header (è necessario attivare mod_logio per usarlo).
%O | Numero di Byte inviati, inclusi gli headers (è necessario attivare mod_logio per usarlo).
%T | Il tempo necessario per servire la richiesta, in secondi.

%{UNITÀ}T

Il tempo necessario per servire la richiesta, in un'unità di tempo definita da UNITÀ (disponibile dalla verione 2.4.13 in poi).
Le unità di tempo valide sono:

Unità | Descrizione
--- | ---
s | secondi
ms | millisecondi
us | microsecondi

%D | Il tempo necessario per servire la richiesta, in millisecondi.
%h | Indirizzo IP del client (hostname remoto).
%{c}h | Come %h, ma riporta sempre l'hostname della connessione TCP reale e non eventuali modifiche all'hostname remoto effettuate da moduli come mod_remoteip.

%{VARIABILE}i

Il contenuto di VARIABILE: la linea (o le linee) dell'header nella richiesta ricevuta dal server.
Le variabili supportate (da LogDoctor) sono:

Variabile | Descrizione
--- | ---
Cookie | cookie della richiesta
Referer | host referente
User-agent | stringa di identificazione del browser o del bot

### Campi scartati da LogDoctor

Ogni campo eccetto i precedenti verrà scartato da LogDoctor.
Nella generazione di una stringa di log di esempio, questi campi appariranno come 'DISCARDED'.
Se non utilizzi i log per altri propositi, è consigliato rimuovere questi campi per velocizzare il processo e ridurre le possibilità di errore.

### Riferimenti

- Lista completa dei formati per i log di accesso di Apache2:
  https://httpd.apache.org/docs/2.4/mod/mod_log_config.html
- Lista completa dei formati di strftime:
  https://cplusplus.com/reference/ctime/strftime/