Apache HTTP Server Version 1.3

Module mod_log_config

Ce module est implémenté dans le fichier mod_log_config.c, et est compilé par défaut dans la version 1.1 d'Apache. Le module mod_log_config remplace le module mod_log_common à partir de la version 1.2. Avant la version 1.2, mod_log_config était un module optionnel. Il permet l'enregistrement de la trace des requêtes reçues par le serveur, sous le format Common Log Format, ou un format personnalisé par l'administrateur.

Résumé

Trois directives sont définies par ce module : TransferLog pour créer un fichier de trace, LogFormat pour définir un format personnalisé, et CustomLog pour définir à la fois un fichier de trace et un format personnalisé en une seule opération. Les directives TransferLog et CustomLog peuvent être utilisées plusieurs fois dans chaque définition de serveur pour obliger la requête a être tracée dans plusieurs fichiers différents (éventuellement sous plusieurs formats différents).

Notes de compatibilité

Ce module se base sur le module mod_log_config distribué avec les précedentes versions d'Apache, transformé pour pouvoir gérer la trace multiple. Vous n'aurez pas besoin de re-configurer Apache pour utiliser les configurations de formats de trace.
Ce module implémente également la directive CookieLog, pour tracer les informations de suivi d'utilisateur mises en oeuvre par le module mod_usertrack. L'utilisation de CookieLog est obsolète, et il vaudra mieux définir un fichier de trace CustomLog pour tracer ces informations.

Formats de fichiers de trace

Sauf mention contraire exprimée par une directive LogFormat, les fichiers de trace crées par TransferLog le seront conformément au standard "Common Log Format" (CLF). Le contenu de chacune des lignes d'un fichier CLF est explicité ci-après. Alternativement, le format du fichier de trace peutêtre personnalisé (et si plusieurs fichiers de trace sont utilisés, chacun peut être défini dans un format différent). Les formats personnalisés sont créés par les directives LogFormat et CustomLog.

Common Log Format

Les fichiers de format "Common Log Format" (CLF) contiennent des lignes d'enregistrement, à raison d'une ligne par requête. Une ligne est composée de plusieurs champs séparés par des espaces :

hôte identité utilisateur_authentifié date requête etat volume

Lorsqu'un token n'a pas de valeur particulière, alors il est réduit à un tiret (-). La signification et les valeurs typiques de cs tokens sont les suivantes :

hôte

Le nom de domaine entièrement qualifié du client, ou son adresse IP si le nom de domaine n'est pas disponible.

identité

Si l'option IdentityCheck est activée et la machine cliente exécute identd, alors ce champ donne l'information d'identification donnée par le client.

utilisateur_authentifié

Si la requête visait un document protégé par mot de passe, alors ce champ contient le nom d'utilisateur utilisé lors de l'authentification.

date

La date et l'heure de la requête, dans le format suivant :

date = [jour/mois/an:heure:minute:seconde zone] jour = 2*digit mois = 3*lettre an = 4*digit heure = 2*digit minute = 2*digit seconde = 2*digit zone = (`+' | `-') 4*digit

requête

La chaîne de requête émise par le client, entre guillemets (").

état

Le code de réponse donné par le serveur pour cette requête.

volume

Le nombre d'octets de l'objet renvoyé au client, hormis toute en-tête.

Custom Log Formats (formats personnalisés)

Le descripteur de format donné par des directives LogFormat et CustomLog est une chaîne de caractères. Cette chaîne est enregistrée dans le fichier de trace pour chaque requête arrivant au serveur. Elle peut contenir des caractères litéraux copiés dans les fichiers de trace, et des expressions variables (précédées de '%') remplacées au moment de l'écriture de l'enregistrement par les valeurs correspondantes :

%...b:          Octets envoyés, non comptées les en-têtes HTTP.
%...f:          Nom de fichier
%...{FOOBAR}e:  Le contenu de la variable d'environnement FOOBAR
%...h:          L'hôte distant
%...{Foobar}i:  Le contenu du champ d'en-tête Foobar: de la requête
                reçue par le serveur.
%...l:          Identité distante (à partir de identd, si fournie)
%...{Foobar}n:  Le conteu d'une note "Foobar" d'un autre module.
%...{Foobar}o:  Le contenu du champ d'en-tête Foobar: dans la réponse.
%...p:          Le port sur lequel la requête a été servie. 
%...P:          Le PID du processus fils qui a servi la requête.
%...r:          La première ligne de la requête
%...s:          Code HTTP. Pour les requêtes redirigées en interne, soit
                le code pour la requête *originale* --- %...>s pour la
                dernière redirection.
%...t:          Temps, au format CLF
%...{format}t:  Temps, selon le format spécifié conformément à la syntaxe
                de la fonction C UNIX strftime(3).
%...T:          Le temps mis pour servir la requête, en secondes.
%...u:          Utilisateur distant (à partir de données
                d'authentification. Peut être vide si (%s) vaut 401)
%...U:          L'URL requise.
%...v:          Le nom du serveur (c-à-d. quel hôte virtuel ?)

La partie '...' peut être vide (ex. "%h %u %r %s %b"), ou préciser les conditions pour lesquelles l'information pourra être enregistrée (ce champ sera remplacé par '-' si ces conditions ne sont pas remplies). Notez qu'aucun caractère d'échappement n'est utilisé dans les chaînes %r, %...i et %...o ; ceux qui ont suivi le développement se souviendront qu'il semblait que ce soit une mauvaise idée à l'époque, et ce n'est pas encore ce quisemble le plus confortable, mais il est difficiel de trouver la méthode idéale pour tous les of `%..i', sauf si nous encodons tout à la mode URL, quitte à perdre la cohérence avec le format CLF.

Le format dans lequel sont exprimées les conditions est une liste de codes de réponse HTTP, qui peuvent éventuellement être précédés d'un signe '!' de négation. Ainsi, %400,501{User-agent}i provoquera l'enregistrement du champ d'en-tête User-agent: sur erreur de type 400 et 501 (Requête erronée, Non implémenté) uniquement ; %!200,304,302{Referer}i enregistre le champ Referer: pour toues les requêtes auxquelles est répondu un code de réponse autre qu'une réponse normale.

Notez que le Common Log Format est représenté par la chaîne "%h %l %u %t \"%r\" %s %b", laquelle peut servir de base de départ si vous désirez personnaliser votre trace (ex. en ajoutant des champs supplémentaires à la fin). Le format de trace combiné/étendu de ttpe NCSA serait représenté par la chaîne "%h %l %u %t \"%r\" %s %b \"%{Referer}i\" \"%{User-agent}i\"".

Fichiers de trace multiples

Les directives TransferLog et CustomLog peuvent apparaître plus d'une fois afin de tracer les requêtes dans plusieurs fichiers sous des formats différents. Chaque requête sera enregistrée dans chacun de ces fichiers dansle format associé à chacune des directives correspondantes.

Utilisation avec des hôtes virtuels

Si une section <VirtualHost> ne contient aucune directive TransferLog ni CustomLog, c'est la trace définie pour le serveur principal qui servira pour cet hôte virtuel. Si elles contiennent une ou plusieurs de ces directives, les requêtes servies par cet hôte virtuel ne seront tracées que dans les fichiers déclarés à l'intérieur de cette section, et à aucun moment dans les traces du serveur principal. Voir les exemples ci-après.

Considérations sur la sécurité

Voir le document notes sur la sécurité pour des détails sur les brêches de sécurité que pourraient constituer des droits d'écriture dans le répertoire contenant les traces, pour un quelconque utilisateur différent de celui qui démarre le serveur.

Directive : CookieLog

Syntaxe : CookieLog nomFichier
Contexte : configuration serveur, hôtes virtuels
Module : mod_cookies
Compatibilité : Disponible à partir de la version 1.2 d'Apache

La directive CookieLog définit le nom du fichier trace pour les cookies. Ce nom est exprimé relativement à la racine ServerRoot. Cette directive n'est inclue que pour assurer la compatibilité avec le module mod_cookies, et est obsolète.

Directive CustomLog

Syntaxe : CustomLog fichier-tube format-ou-identificateur
Contexte : configuration serveur, hôtes virtuels
Statut : Base
Compatibilité : L'idenitficateur n'est reconnu qu'à partir de la version 1.3 d'Apache
Module : mod_log_config

Le premier argument est le nom de fichier de trace. Il est défini exactement comme l'argument de la directive TransferLog ; c'est-à-dire, comme un chemin absolu, ou relatif par rapport à la racine serveur courante.

L'aegument format spécifie le format dans lequel les lignes d'enregistrement seront écrites. Les options disponibles pour le format sont exactement les mêmes que pour la directive LogFormat. Si le format inclue des espaces litéraux, (ce qui sera pratiquement toujours le cas) alors la chaîne entière devra être mise entre apostrophes.

A partir de la version 1.3 d'Apache, vous pouvez remplacer l'expression exhaustive du format par un identificateur (un raccourci), lequel aura été défini par une directive LogFormat.

Directive : LogFormat

Syntaxe : LogFormat format [raccourci]
Défaut:

LogFormat "%h %l %u %t \"%r\"
%s %b"

Contexte : configuration serveur, hôtes virtuels
Statut : Base
Compatibilité : Les racourcis ne sont disponibles qu'à partir de la version 1.3 d'Apache or later
Module: mod_log_config

Définit le format du fichier de trace par défaut spécifié dans la directive TransferLog. Voir la section sur les formats personnalisés pour plus de détails sur les arguments de l'attribut de format.

Si vous précisez un raccourci pour ce format, vous pourrez spécifier ce format par ce raccourci dans d'autres directives LogFormat ou CustomLog plutôt que réécrire toute la chaîne de description.

Une directive LogFormat qui définit un raccourci n'a aucune autre fonction -- c'est-à-dire, elle ne fait que définir le raccourci, sans appliquer le format à quoi que ce soit, ni l'attribuer au défaut.

Directive : TransferLog

Syntaxe : TransferLog fichier-tube
Défaut : none
Contexte : configuration serveur, hôtes virtuels
Statut : Base
Module : mod_log_config

La directive TransferLog ajoute la définition d'un fichier de trace sous un format défini par la directive LogFormat la plus récente, ou Common Log Format si aucun autre format par défaut n'a été spécifié.

Fichier-tube est soit :

Un nom de fichier: exprimé relativement à la racine ServerRoot.
`|' suivi d'une commande: Un programme qui reçoit les informations de trace sur son entrée standard. Notez qu'une nouvelle instance du programme ne sera pas démarrée pour un VirtualHost qui hériterait des fichiers de trace du serveur principal.

Securité : si la trace est redirigée sur un programme, alors ce dernier sera exécuté sous l'utilisateur qui a démarré httpd. Cet utilisateur peut être root si le serveur a été démarré sous root ; assurez-vous que ce programme est sûr.

Apache HTTP Server Version 1.3