Serveur HTTP Apache Version 2.5
Description: | Journalisation des requêtes envoyées au serveur |
---|---|
Statut: | Base |
Identificateur de Module: | log_config_module |
Fichier Source: | mod_log_config.c |
Ce module apporte une grande souplesse dans la journalisation des requêtes des clients. Les journaux sont écrits sous un format personnalisable, et peuvent être enregistrés directement dans un fichier, ou redirigés vers un programme externe. La journalisation conditionnelle est supportée, si bien que des requêtes individuelles peuvent être incluses ou exclues des journaux en fonction de leur caractéristiques.
Ce module fournit trois directives : TransferLog
crée un fichier
journal, LogFormat
définit un format personnalisé, et CustomLog
définit un fichier journal et un format en
une seule étape. Pour journaliser les requêtes dans plusieurs
fichiers, vous pouvez utiliser plusieurs fois les directives
TransferLog
et
CustomLog
dans chaque serveur.
L'argument format des directives LogFormat
et CustomLog
est une chaîne de
caractères. Cette chaîne définit le format de la journalisation des
requêtes dans le fichier journal. Elle peut contenir des caractères
littéraux qui seront reproduits dans le fichier journal, et les
caractères de contrôle de style C "\n" et "\t" représentant
respectivement une nouvelle ligne et une tabulation. Les guillemets
et les anti-slashes littéraux doivent être échappés à l'aide
d'anti-slashes.
Les caractéristiques de la requête en elle-même sont journalisées
en insérant des directives "%
" dans la chaîne de
format, celles-ci étant remplacées dans le fichier journal par
certaines valeurs comme suit :
Chaîne de format | Description | ||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|
%% |
Le signe "pourcentage" | ||||||||||
%a |
L'adresse IP distante (voir le module
mod_remoteip ). | ||||||||||
%{c}a |
Adresse IP distante de la connexion(voir le module
mod_remoteip ) | ||||||||||
%A |
L'adresse IP locale | ||||||||||
%B |
La taille de la réponse en octets, en excluant les en-têtes HTTP. | ||||||||||
%b |
La taille de la réponse en octets, en excluant les en-têtes
HTTP. Au format CLF , c'est à dire un '- ' à la
place d'un 0 lorsqu'aucun octet n'est renvoyé. | ||||||||||
%{NOMVAR}C |
Le contenu du cookie NOMVAR dans la requête envoyée au serveur. Seuls les cookies version 0 sont pleinement supportés. | ||||||||||
%D |
Le temps mis à servir la requête, en microsecondes. Voir %T pour plus de détails | ||||||||||
%{NOMVAR}e |
Le contenu de la variable d'environnement NOMVAR | ||||||||||
%f |
Nom de fichier | ||||||||||
%h |
Serveur distant. Contiendra l'adresse IP si la directive
HostnameLookups est définie
à Off , ce qui est sa valeur par défaut. Si cette
adresse IP n'est enregistrée que pour certains serveurs, vous
avez probablement défini des directives de contrôle d'accès qui
mentionnent ces derniers par leurs noms. Voir la documentation de Require
host. Ce format peut être impacté par la modifications
du nom d'hote distant par des modules comme mod_remoteip . | ||||||||||
%{c}h |
Semblable à %h , mais exploite toujours le nom d'hôte de la connection
TCP sous-jacente, en ignorant toute modification réalisée sur le nom d'hôte distant
par des modules tels que mod_remoteip . | ||||||||||
%H |
Le protocole de la requête | ||||||||||
%{NOMVAR}i |
Le contenu des lignes d'en-tête
NOMVAR: dans la requête envoyée au
serveur. Ces en-têtes sont ajoutés par d'autres modules (par
exemple mod_headers ). Si vous êtes intéressé
par ce qu'était l'en-tête de la requête avant d'être modifié
par la plupart des modules, utilisez
mod_setenvif pour copier l'en-tête dans une
variable d'environnement interne et journaliser sa valeur via
le champ %{VARNAME}e décrit plus haut.
| ||||||||||
%k |
Nombre de requêtes persistantes en cours pour cette
connexion. Interessant si la directive KeepAlive est utilisée ; par exemple,
'1' signifie la première requête après la requête initiale, '2'
la seconde, etc... ; autrement, il s'agit toujours de 0
(indiquant la requête initiale). | ||||||||||
%l |
Le nom de connexion distant (en provenance d'identd, si
disponible). Affiche un tiret, sauf si
mod_ident est présent et si IdentityCheck est à
On . | ||||||||||
%L |
L'identifiant du message de journalisation de la requête dans le journal des erreurs (ou '-' si aucun message n'a été enregistré dans le journal des erreurs pour cette requête). Consulter le journal d'erreurs pour voir quelle requête a généré quelle erreur. | ||||||||||
%{c}L |
L'identifiant du message de journalisation de la connexion dans le journal des erreurs (ou '-' si aucun message n'a été enregistré dans le journal des erreurs pour cette requête). Consulter le journal d'erreurs pour voir quelle requête a généré quelle erreur. | ||||||||||
%m |
La méthode de la requête | ||||||||||
%{NOMVAR}n |
Le contenu de la note NOMVAR en provenance d'un autre module. | ||||||||||
%{NOMVAR}o |
Le contenu de la ligne d'en-tête
NOMVAR: de la réponse. | ||||||||||
%p |
Le port canonique du serveur servant la requête | ||||||||||
%{format}p |
Le port canonique du serveur servant la requête ou le
véritable port du serveur ou le véritable port du client. les
formats valides sont canonical , local ,
ou remote .
| ||||||||||
%P |
Le numéro de processus du processus enfant qui a servi la requête. | ||||||||||
%{format}P |
Le numéro de processus ou le numéro de thread du processus
enfant qui a servi la requête. Les formats valides sont
pid , tid , et hextid .
| ||||||||||
%q |
La chaîne d'arguments (préfixée par un ? si une
chaîne d'arguments existe, sinon une chaîne vide) | ||||||||||
%r |
La première ligne de la requête | ||||||||||
%R |
Le gestionnaire qui génère la réponse (s'il y en a un). | ||||||||||
%s |
Statut. Pour les requêtes redirigées en interne, il s'agit
du statut de la requête *originale* --- %>s pour
la dernière. | ||||||||||
%t |
Date à laquelle la requête a été reçue (au format anglais standard) | ||||||||||
%{format}t |
La date, sous la forme spécifiée par format, qui devrait
être au format étendu strftime(3) (éventuellement
localisé). Si le format commence par begin: (valeur
par défaut), la date est extraite au début du traitement de la
requête ; s'il commence par end: , la date
correspond au moment où l'entrée du journal est inscrite, par
conséquent vers la fin du traitement de la requête. Hormis les
formats supportés par strftime(3) , les formats
suivants sont aussi disponibles :
strftime(3) dans la même chaîne de
format. Par contre, vous pouvez utiliser plusieurs symboles
%{format}t . | ||||||||||
%T |
Le temps mis pour servir la requête, en secondes. Le temps commence à être mesuré au moment où la première ligne de la requête HTTP est transmise par le système d'exploitation au serveur HTTP, et se termine au moment où le dernier octet de la réponse est envoyé au système d'exploitation par le serveur HTTP. Le temps mesuré n'inclut donc aucune des rubriques suivantes :
| ||||||||||
%{UNIT}T |
Le temps mis pour traiter la requête dans une unité définie
par UNIT . Les valeurs d'unité valides sont
ms pour millisecondes, us pour
microsecondes et s pour secondes. Si
UNIT est omis, la valeur de l'unité par défaut est
la seconde ; spécifier la valeur d'unité us revient
à utiliser le format %D . La possibilité de
spécifier une valeur d'unité avec le format %T est
disponible depuis la version 2.4.13 du serveur HTTP Apache. | ||||||||||
%u |
L'utilisateur distant (en provenance d'auth ; peut être faux
si le statut de retour (%s ) est 401). | ||||||||||
%U |
Le chemin de la requête, à l'exclusion de toute chaîne d'arguments. | ||||||||||
%v |
Le nom canonique du serveur qui a servi la requête, défini
par la directive ServerName . | ||||||||||
%V |
La nom du serveur en tenant compte de la définition de la
directive UseCanonicalName . | ||||||||||
%X |
Statut de la connexion lorsque la réponse a été renvoyée
:
| ||||||||||
%I |
Le nombre d'octets reçus, en comptant la requête et les
en-têtes, ne peut être nul. Nécessite l'activation de
mod_logio . | ||||||||||
%O |
Nombre d'octets envoyés, y compris les en-têtes. Peut être
nul dans les rares cas où une requête est avortée avant que la
réponse ne soit envoyée. Nécessite l'activation de
mod_logio . | ||||||||||
%S |
Nombre d'octets transmis en émission et réception y compris
la requête et les en-têtes ; cette valeur ne peut pas être
nulle, il s'agit de la combinaison de %I et %O. Vous devez
activer mod_logio pour utiliser cette chaîne de
format. | ||||||||||
%{VARNAME}^ti |
Le contenu de la variable VARNAME:
spécifiée dans la requête envoyée au serveur. | ||||||||||
%{VARNAME}^to |
Le contenu de la variable VARNAME:
spécifiée dans la réponse envoyée par le serveur. |
Il est possible de restreindre l'enregistrement de certains
éléments
en fonction du code de statut de la réponse, en insérant une liste
de codes de statut séparés par des virgules immédiatement après le
caractère "%". Par exemple, "%400,501{User-agent}i"
n'enregistrera l'en-tête User-agent
que dans le cas
d'une erreur 400 ou 501. Avec les autres codes de statut, c'est la
chaîne littérale "-"
qui sera enregistrée. La liste
de codes peut être précédée d'un "!
" pour inverser la
condition : "%!200,304,302{Referer}i"
enregistre
l'en-tête Referer
pour toutes les requêtes qui
ne renvoient pas un des trois codes spécifiés.
Les modificateurs "<" et ">" peuvent être utilisés pour
les requêtes qui ont été redirigées en interne afin de choisir si
c'est respectivement la requête originale ou finale qui doit être
consultée. Par défaut, les directives %s, %U, %T, %D,
et %r
consultent la requête originale, alors que
toutes les autres consultent la requête finale. Ainsi, par
exemple, on peut utiliser %>s
pour enregistrer le
statut final de la requête, et %<u
pour
enregistrer l'utilisateur authentifié à l'origine pour une requête
redirigée en interne vers une ressource sans authentification.
Pour des raisons de sécurité, à partir de la version 2.0.46,
les caractères non imprimables et autres caractères spéciaux dans
les directives %r
, %i
et %o
doivent être échappés à l'aide des séquences
\xhh
,
où hh est le code hexadécimal du caractère spécial.
Comme exceptions à cette règle, les caractères "
et
\
doivent être échappés par un anti-slash, et tous
les "blancs" doivent être écrits selon leur notation de style C
(\n
, \t
, etc...). Avant la version
2.0.46, aucun échappement n'était effectué sur ces chaînes, et il
fallait être très prudent lors de l'exploitation des journaux
bruts.
A la différence de la version 1.3, depuis httpd 2.0, les chaînes
de format %b
et %B
ne représentent pas
le nombre d'octets envoyés au client, mais simplement la taille en
octets de la réponse HTTP (les deux étant différents, par exemple,
si la connexion est abandonnée, ou si SSL est utilisé). Le format
%O
fourni par mod_logio
,
enregistrera le nombre réel d'octets envoyés sur le réseau.
Note : mod_cache
est implémenté en tant que
gestionnaire basique et non en tant que gestionnaire standard.
C'est pourquoi la chaîne de format %R
ne renverra pas
d'information à propos du gestionnaire lorsqu'une mise en cache de
contenu entre en jeu.
Note : la présence du caractère '^' au début d'une chaîne de format de trois caractères n'a aucune incidence sur la signification de cette chaîne, mais il doit être le premier caractère de toute chaîne de format de trois caractères nouvellement créée, afin d'éviter d'éventuels conflits avec des chaînes de format qui utilisent des caractères littéraux adjacents à un spécificateur de format tel que "%Dus".
Quelques chaînes de format couramment utilisées :
"%h %l %u %t \"%r\" %>s %b"
"%v %h %l %u %t \"%r\" %>s %b"
"%h %l %u %t \"%r\" %>s %b \"%{Referer}i\"
\"%{User-agent}i\""
"%{Referer}i -> %U"
"%{User-agent}i"
Vous pouvez utiliser plusieurs fois la directive
%{format}t
pour construire un format de temps
utilisant les symboles de format étendus tels que
msec_frac
:
"%{%d/%b/%Y %T}t.%{msec_frac}t %{%z}t"
Voir le document conseils à matière de sécurité pour plus de détails sur les raisons pour lesquelles votre sécurité pourrait être compromise, si le répertoire où sont stockés les fichiers journaux sont inscriptibles par tout autre utilisateur que celui qui démarre le serveur.
Description: | Enregistre les entrées du journal dans un tampon en mémoire avant de les écrire sur disque |
---|---|
Syntaxe: | BufferedLogs On|Off |
Défaut: | BufferedLogs Off |
Contexte: | configuration globale |
Statut: | Base |
Module: | mod_log_config |
Lorsque la directive BufferedLogs
est à
"on", mod_log_config
stocke de nombreuses entrées
du journal en mémoire, et les écrit d'un seul bloc sur disque,
plutôt que de les écrire après chaque requête. Sur certains
systèmes, ceci peut améliorer l'efficacité des accès disque, et par
conséquent les performances. La directive ne peut être définie
qu'une seule fois pour l'ensemble du serveur ; elle ne peut pas être
définie au niveau d'un serveur virtuel.
Description: | Définit le nom et le format du fichier journal |
---|---|
Syntaxe: | CustomLog fichier|pipe|provider
format|alias
[env=[!]variable-environnement|
expr=expression] |
Contexte: | configuration globale, serveur virtuel |
Statut: | Base |
Module: | mod_log_config |
La directive CustomLog
permet de contrôler
la journalisation des requêtes destinées au serveur. Un format de
journal est spécifié, et la journalisation peut s'effectuer de
manière conditionnelle en fonction des caractéristiques de la
requête en utilisant des variables d'environnement.
Le premier argument, qui spécifie l'emplacement où les journaux seront écrits, accepte deux types de valeurs :
ServerRoot
.|
", suivi du chemin vers un
programme qui recevra les informations de la journalisation sur
son entrée standard. Voir les notes à propos de la journalisation redirigée pour plus
d'informations.
Si les journaux sont redirigés vers un programme, ce dernier
s'exécutera sous l'utilisateur qui a démarré
httpd
. Ce sera l'utilisateur root si le serveur
a été démarré par root ; vérifiez que le programme est
sécurisé.
Lors de la spécification d'un chemin de fichier sur les plate-formes non-Unix, il faut prendre soin de ne pas oublier que seuls les slashes directs doivent être utilisés, même si la plate-forme autorise l'emploi d'anti-slashes. D'une manière générale, c'est une bonne idée que de n'utiliser que des slashes directs dans les fichiers de configuration.
mod_journald
ou
mod_syslog
:
# Journalisation CustomLog vers journald CustomLog "journald" "%h %l %u %t \"%r\" %>s %b" # Journalisation CustomLog vers syslog avec l'option "user" CustomLog "syslog:user" "%h %l %u %t \"%r\" %>s %b"
Le second argument permet de définir ce qui va être écrit dans le
fichier journal. Il peut contenir soit un alias prédéfini
par une directive LogFormat
, soit une chaîne de
format explicite comme décrit dans la section formats de journaux.
Par exemple, les deux blocs de directives suivants produisent le même effet :
# Journal personnalisé avec alias de format LogFormat "%h %l %u %t \"%r\" %>s %b" common CustomLog "logs/access_log" common # Journal personnalisé avec chaîne de format explicite CustomLog "logs/access_log" "%h %l %u %t \"%r\" %>s %b"
Le troisième argument est optionnel et permet de contrôler si une
requête doit être ou non journalisée. Dans le cas d'une clause
'env=!nom
', la condition peut être la
présence ou l'absence d'une variable particulière dans
l'environnement du serveur. Dans le cas
d'une clause 'expr=expression', la condition consiste
en une expression booléenne
quelconque. Si la condition n'est pas vérifiée, la requête ne sera
pas journalisée. D'éventuelles références à des en-têtes HTTP dans
l'expression rationnelle n'entraîneront pas l'ajout des noms
d'en-tête correspondants à l'en-tête Vary.
Les variables d'environnement peuvent être définies au niveau de
chaque requête en utilisant les modules
mod_setenvif
et/ou mod_rewrite
.
Par exemple, si vous voulez enregistrer les requêtes pour toutes les
images GIF sur votre serveur dans un fichier journal séparé, et pas
dans votre journal principal, vous pouvez utiliser :
SetEnvIf Request_URI \.gif$ gif-image CustomLog "gif-requests.log" common env=gif-image CustomLog "nongif-requests.log" common env=!gif-image
Ou, pour reproduire le comportement de l'ancienne directive RefererIgnore, vous pouvez utiliser :
SetEnvIf Referer example\.com localreferer CustomLog "referer.log" referer env=!localreferer
Description: | Définit le nom et le format du fichier journal |
---|---|
Syntaxe: | GlobalLog file|pipe|provider
format|nickname
[env=[!]environment-variable|
expr=expression] |
Contexte: | configuration globale |
Statut: | Base |
Module: | mod_log_config |
Compatibilité: | Disponible à partir de la version 2.4.19 du serveur HTTP Apache |
La directive GlobalLog
permet de spécifier un
journal partagé entre le serveur principal et tous les serveurs virtuels
définis.
Elle est identique à la directive CustomLog
à ces
différences près :
CustomLog
définie globalement, elle est prise en compte par les serveurs virtuels
qui définissent leur propre directive CustomLog
.Description: | Décrit un format utilisable dans un fichier journal |
---|---|
Syntaxe: | LogFormat format|alias
[alias] |
Défaut: | LogFormat "%h %l %u %t \"%r\" %>s %b" |
Contexte: | configuration globale, serveur virtuel |
Statut: | Base |
Module: | mod_log_config |
Cette directive permet de spécifier le format du fichier journal des accès.
La directive LogFormat
se présente sous
deux formes. Sous la première forme, qui ne possède qu'un seul
argument, la directive définit le format qui sera utilisé dans les
journaux spécifiés par les directives
TransferLog
ultérieures. L'argument unique
peut contenir un format explicite comme décrit dans la
section formats de journaux personnalisés
ci-dessus. Il peut aussi contenir un alias faisant
référence à un format de journal prédéfini par une directive
LogFormat
comme décrit plus loin.
Sous sa seconde forme, la directive
LogFormat
associe un format
explicite à un alias. Cet alias peut
ensuite s'utiliser dans les directives
LogFormat
ou CustomLog
ultérieures, ce qui
évite d'avoir à répéter l'ensemble de la chaîne de format. Une
directive LogFormat
qui définit un alias
ne fait rien d'autre -- c'est à dire qu'elle ne
fait que définir l'alias, elle n'applique pas le format et n'en
fait pas le format par défaut. Par conséquent, elle n'affecte pas
les directives TransferLog
ultérieures. En
outre, la directive LogFormat
ne peut pas
utiliser un alias pour en définir un autre. Notez que l'alias ne
doit pas contenir de caractère pourcent (%
).
LogFormat "%v %h %l %u %t \"%r\" %>s %b" serveur_virtuel_commun
Description: | Spécifie l'emplacement d'un fichier journal |
---|---|
Syntaxe: | TransferLog fichier|pipe |
Contexte: | configuration globale, serveur virtuel |
Statut: | Base |
Module: | mod_log_config |
Cette directive possède exactement les mêmes arguments et produit
les mêmes effets que la directive CustomLog
, à l'exception qu'elle
ne permet pas de spécifier un format de journal explicite ou la
journalisation conditionnelle des requêtes. En l'occurrence, le
format de journal est déterminé par la dernière définition d'une
directive LogFormat
qui ne définit pas d'alias. Si aucun format particulier n'a été
spécifié, c'est le Common Log Format qui sera utilisé.
LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\"" TransferLog "logs/access_log"