Fichiers journaux

Avertissement � propos de la s�curit�

Tout utilisateur qui dispose de droits en �criture sur le r�pertoire dans lequel Apache �crit ses journaux pourra quasi certainement avoir acc�s � l'uid sous lequel le serveur est d�marr�, en l'occurrence habituellement root. N'accordez PAS aux utilisateurs l'acc�s en �criture au r�pertoire dans lequel les journaux sont stock�s sans savoir exactement quelles en seraient les cons�quences ; voir le document conseils sur la s�curit� pour plus de d�tails.

En outre, les journaux peuvent contenir des informations fournies directement par un client, sans caract�res d'�chappement. Des clients mal intentionn�s peuvent donc ins�rer des caract�res de contr�le dans les journaux, et il convient par cons�quent �tre tr�s prudent lors de la manipulation des journaux bruts.

Journal des erreurs

Le journal des erreurs du serveur, dont le nom et la localisation sont d�finis par la directive ErrorLog, est le journal le plus important. C'est dans celui-ci que le d�mon Apache httpd va envoyer les informations de diagnostic et enregistrer toutes les erreurs qui surviennent lors du traitement des requ�tes. Lorsqu'un probl�me survient au d�marrage du serveur ou pendant son fonctionnement, la premi�re chose � faire est de regarder dans ce journal, car il vous renseignera souvent sur le probl�me rencontr� et la mani�re d'y rem�dier.

Le journal des erreurs est habituellement enregistr� dans un fichier (en g�n�ral error_log sur les syst�mes de type Unix et error.log sur Windows et OS/2). Sur les syst�mes de type Unix, le serveur peut aussi enregistrer ses erreurs dans syslog ou les rediriger vers un programme par l'interm�diaire d'un tube de communication (pipe).

Le format du journal des erreurs est descriptif et de forme relativement libre. Certaines informations apparaissent cependant dans la plupart des entr�es du journal. Voici un message typique � titre d'exemple :

Le premier champ de l'entr�e du journal est la date et l'heure du message. Le second champ indique la s�v�rit� de l'erreur rapport�e. La directive LogLevel permet de restreindre le type des erreurs qui doivent �tre enregistr�es dans le journal des erreurs en d�finissant leur niveau de s�v�rit�. Le troisi�me champ contient l'adresse IP du client qui a g�n�r� l'erreur. Vient ensuite le message proprement dit, qui indique dans ce cas que le serveur a �t� configur� pour interdire l'acc�s au client. Le serveur indique le chemin syst�me du document requis (et non son chemin web).

Une grande vari�t� de messages diff�rents peuvent appara�tre dans le journal des erreurs. La plupart d'entre eux sont similaires � l'exemple ci-dessus. Le journal des erreurs peut aussi contenir des informations de d�bogage en provenance de scripts CGI. Toute information qu'un script CGI �crit sur la sortie d'erreurs standard stderr sera recopi�e telle quelle dans le journal des erreurs.

Il n'est pas possible de personnaliser le journal des erreurs en ajoutant ou en supprimant des informations. Cependant, les entr�es du journal des erreurs qui concernent certaines requ�tes poss�dent des entr�es correspondantes dans le journal des acc�s. Ainsi, l'entr�e de l'exemple ci-dessus correspond � une entr�e du journal des acc�s avec un code de statut 403. Etant donn� qu'il est possible de personnaliser le journal des acc�s, vous pouvez obtenir d'avantage d'informations sur les circonstances d'une erreur en consultant ce journal.

Pendant la phase de test, il est souvent utile de visualiser en continu le journal des erreurs afin de d�tecter tout probl�me �ventuel. Sur les syst�mes de type Unix, ceci s'effectue � l'aide de la commande :

Journal des acc�s

Le journal des acc�s au serveur enregistre toutes les requ�tes que traite ce dernier. La localisation et le contenu du journal des acc�s sont d�finis par la directive CustomLog. La directive LogFormat permet de simplifier la s�lection du contenu du journal. Cette section d�crit comment configurer le serveur pour l'enregistrement des informations dans le journal des acc�s.

Bien �videmment, le stockage d'informations dans le journal des acc�s n'est que le point de d�part de la gestion de la journalisation. L'�tape suivante consiste � analyser ces informations de fa�on � pouvoir en extraire des statistiques utiles. L'analyse de journaux en g�n�ral est hors du cadre de ce document et ne fait pas vraiment partie int�grante du travail du serveur web lui-m�me. Pour plus d'informations � propos de ce sujet et des applications d�di�es � l'analyse de journaux, vous pouvez vous r�f�rer � Open Directory ou Yahoo.

Diff�rentes versions du d�mon Apache httpd utilisaient d'autres modules et directives pour contr�ler la journalisation des acc�s, � l'instar de mod_log_referer, mod_log_agent, et de la directive TransferLog. La directive CustomLog rassemble d�sormais les fonctionnalit�s de toutes les anciennes directives.

Le format du journal des acc�s est hautement configurable. Il est d�fini � l'aide d'une cha�ne de format qui ressemble sensiblement � la cha�ne de format de style langage C de printf(1). Vous trouverez quelques exemples dans les sections suivantes. Pour une liste exhaustive de ce que peut contenir une cha�ne de format, vous pouvez vous r�f�rer au chapitre cha�nes de format de la documentation du module mod_log_config.

Format habituel du journal

Voici une configuration typique pour le journal des acc�s :

Ici est d�finie l'identit� common qui est ensuite associ�e � une cha�ne de format de journalisation particuli�re. La cha�ne de format est constitu�e de directives d�butant par le caract�re %, chacune d'entre elles indiquant au serveur d'enregistrer un �l�ment particulier d'information. Des caract�res litt�raux peuvent �galement �tre ins�r�s dans la cha�ne de format ; il seront copi�s tels quels dans le flux de sortie destin� � la journalisation. Les guillemets (") doivent �tre prot�g�es en les faisant pr�c�der d'un anti-slash (\) afin qu'ils ne soient pas interpr�t�s comme la fin de la cha�ne de format. La cha�ne de format peut aussi contenir les caract�res de contr�le sp�ciaux "\n" et "\t" pour ins�rer respectivement un passage � la ligne et une tabulation.

La directive CustomLog d�finit un nouveau fichier journal en l'associant � l'identit� pr�c�demment d�finie. Le chemin du nom de fichier associ� au journal des acc�s est relatif au chemin d�fini par la directive ServerRoot, sauf s'il d�bute par un slash.

La configuration ci-dessus va enregistrer les entr�es de journalisation selon un format connu sous le nom de Common Log Format (CLF) pour "Format de journalisation standard". Ce format standard peut �tre produit par de nombreux serveurs web diff�rents et lu par de nombreux programmes d'analyse de journaux. Les entr�es de fichier journal g�n�r�es selon le format CLF ressemblent � ceci :

Chaque partie de cette entr�e de journal est d�crite dans ce qui suit.

127.0.0.1 (%h)

Il s'agit de l'adresse IP du client (l'h�te distant) qui a envoy� la requ�te au serveur. Si la directive HostnameLookups est positionn�e � On, le serveur va essayer de d�terminer le nom de l'h�te et de l'enregistrer � la place de l'adresse IP. Cette configuration n'est cependant pas recommand�e car elle peut ralentir le serveur de mani�re significative. Il est par cons�quent pr�f�rable d'utiliser un processeur d'analyse de journaux a posteriori tel que logresolve pour d�terminer les noms d'h�te. L'adresse IP indiqu�e ici n'est pas n�cessairement l'adresse IP de la machine devant laquelle se trouve l'utilisateur. Si un serveur mandataire s'intercale entre le serveur et l'utilisateur, l'adresse indiqu�e sera celle du mandataire et non celle de la machine � l'origine de la requ�te.

- (%l)

Le "trait d'union" indique que la portion d'information correspondante n'est pas disponible. Dans le cas pr�sent, l'information non disponible est l'identit� (RFC 1413) du client telle que d�termin�e par identd sur la machine cliente. Cette information est tr�s peu fiable et ne devrait jamais �tre utilis�e, sauf dans le cas de r�seaux internes �troitement contr�l�s. Le d�mon httpd ne cherchera d'ailleurs � obtenir cette information que si la directive IdentityCheck est positionn�e � On.

frank (%u)

Il s'agit de l'identifiant utilisateur de la personne qui a demand� le document, issu d'une authentification HTTP. Ce m�me identifiant est en g�n�ral fourni aux scripts CGI par l'interm�diaire de la valeur de la variable d'environnement REMOTE_USER. Si le statut de la requ�te (voir plus loin) est 401, cette identifiant n'est pas fiable car l'utilisateur n'est pas encore authentifi�. Si le document n'est pas prot�g� par mot de passe, cette partie d'information sera repr�sent�e par "-", comme la partie pr�c�dente.

[10/Oct/2000:13:55:36 -0700] (%t)

L'heure � laquelle la requ�te a �t� re�ue. Le format est le suivant :

[jour/mois/ann�e:heure:minutes:secondes zone]
jour = 2*chiffre
mois = 3*lettre
ann�e = 4*chiffre
heure = 2*chiffre
minutes = 2*chiffre
secondes = 2*chiffre
zone = (`+' | `-') 4*chiffre

Il est possible de modifier le format d'affichage de l'heure en sp�cifiant %{format}t dans la cha�ne de format du journal, o� format est une cha�ne de format de m�me forme que celle de la fonction strftime(3) de la biblioth�que C standard.

"GET /apache_pb.gif HTTP/1.0" (\"%r\")

La ligne de la requ�te du client est plac�e entre guillemets. Elle contient de nombreuses informations utiles. Tout d'abord, la m�thode utilis�e par le client est GET. Ensuite, le client a demand� la ressource /apache_pb.gif, et enfin, le client a utilis� le protocole HTTP/1.0. Il est �galement possible d'enregistrer s�par�ment une ou plusieurs parties de la requ�te. Par exemple, la cha�ne de format "%m %U %q %H" va enregistrer la m�thode, le chemin, la cha�ne de la requ�te et le protocole, ce qui donnera le m�me r�sultat que "%r".

200 (%>s)

C'est le code de statut que le serveur retourne au client. Cette information est tr�s importante car elle indique si la requ�te a fait l'objet d'une r�ponse positive (codes commen�ant par 2), une redirection (codes commen�ant par 3), une erreur due au client (codes commen�ant par 4), ou une erreur due au serveur (codes commen�ant par 5). Vous trouverez la liste compl�te des codes de statut possibles dans la specification HTTP (RFC2616 section 10).

2326 (%b)

La derni�re partie indique la taille de l'objet retourn� au client, en-t�tes non compris. Si aucun contenu n'a �t� retourn� au client, cette partie contiendra "-". Pour indiquer l'absence de contenu par "0", utilisez %B au lieu de %b.

Combined Log Format (Format de journalisation combin�)

Une autre cha�ne de format couramment utilis�e est le "Combined Log Format" (Format de journalisation combin�). Il s'utilise comme suit :

Ce format est identique au Common Log Format, avec deux champs suppl�mentaires. Chacun de ces deux champs utilise la directive commen�ant par le caract�re "%" %{header}i, o� header peut �tre n'importe quel en-t�te de requ�te HTTP. Avec ce format, le journal des acc�s se pr�sentera comme suit :

Les champs suppl�mentaires sont :

"http://www.example.com/start.html" (\"%{Referer}i\")

L'en-t�te "Referer" (sic) de la requ�te HTTP. Il indique le site depuis lequel le client pr�tend avoir lanc� sa requ�te. (Ce doit �tre la page qui contient un lien vers /apache_pb.gif ou inclut ce dernier fichier).

"Mozilla/4.08 [en] (Win98; I ;Nav)" (\"%{User-agent}i\")

L'en-t�te User-Agent de la requ�te HTTP. C'est une information d'identification que le navigateur du client envoie � propos de lui-m�me.

Journaux d'acc�s multiples

Plusieurs journaux d'acc�s peuvent �tre cr��s en sp�cifiant tout simplement plusieurs directives CustomLog dans le fichier de configuration. Par exemple, les directives suivantes vont cr�er trois journaux d'acc�s. Le premier contiendra les informations de base CLF, le second les informations du Referer, et le troisi�me les informations sur le navigateur. Les deux derni�res directives CustomLog montrent comment simuler les effets des directives ReferLog et AgentLog.

Cet exemple montre aussi qu'il n'est pas obligatoire d'associer une cha�ne de format � un alias au moyen de la directive LogFormat. Elle peut �tre d�finie directement dans la ligne de la directive CustomLog.

Journalisation conditionnelle

Il est parfois souhaitable d'exclure certaines entr�es des journaux d'acc�s en fonction des caract�ristiques de la requ�te du client. On peut facilement y parvenir � l'aide des variables d'environnement. Tout d'abord, une variable d'environnement doit �tre d�finie pour indiquer que la requ�te remplit certaines conditions. Pour ceci, on utilise en g�n�ral la directive SetEnvIf, puis la clause env= de la directive CustomLog pour inclure ou exclure les requ�tes pour lesquelles la variable d'environnement est d�finie. Quelques exemples :

Autre exemple, imaginons l'enregistrement des requ�tes en provenance d'utilisateurs de langue anglaise dans un journal, et celles des autres utilisateurs dans un autre journal.

Bien que nous venions de montrer que la journalisation conditionnelle est souple et tr�s puissante, cette m�thode de contr�le du contenu des journaux n'est pas la seule. Les fichiers journaux sont plus utiles quand ils contiennent un enregistrement complet de l'activit� du serveur, et il est souvent plus ais� de simplement traiter a posteriori les fichiers journaux pour supprimer les requ�tes que vous ne voulez pas y voir appara�tre.

Rotation des journaux

M�me dans le cas d'un serveur mod�r�ment sollicit�, la quantit� d'informations stock�es dans les fichiers journaux est tr�s importante. Le fichier journal des acc�s grossit en g�n�ral d'1 Mo ou plus toutes les 10000 requ�tes. Il est par cons�quent n�cessaire d'effectuer p�riodiquement la rotation des journaux en d�pla�ant ou supprimant les fichiers correspondants. On ne peut pas le faire pendant que le serveur est en cours d'ex�cution, car Apache va continuer � �crire dans l'ancien fichier journal aussi longtemps qu'il le maintiendra ouvert. C'est pourquoi le serveur doit �tre red�marr� apr�s le d�placement ou la suppression des fichiers journaux de fa�on � ce qu'il en ouvre de nouveaux.

Avec un red�marrage graceful, on peut faire en sorte que le serveur ouvre de nouveaux fichiers journaux sans perdre de connexions existantes ou en cours avec les clients. Cependant, pour que ceci soit possible, le serveur doit continuer � �crire dans les anciens fichiers journaux pendant qu'il termine le traitement des requ�tes en cours. Il est donc n�cessaire d'attendre un certain temps apr�s le r�d�marrage avant d'effectuer tout traitement sur les fichiers journaux. Voici un sc�nario typique dans lequel on effectue une simple rotation des journaux en compressant les anciens fichiers correspondants afin de gagner de l'espace disque :

La section suivante pr�sente une autre m�thode de rotation des journaux qui consiste � utiliser les journaux redirig�s.

Journaux redirig�s

Nous avons vu que le d�mon httpd �crivait les informations de journalisation des erreurs et des acc�s dans un fichier journal ; il peut �galement rediriger ces informations vers un autre processus par l'interm�diaire d'un tube de communication (pipe). Cette fonctionnalit� am�liore consid�rablement la souplesse de la journalisation, sans ajouter de code au serveur principal. Pour rediriger les informations de journalisation vers un tube de communication, remplacez simplement le nom de fichier journal par le caract�re pipe "|", suivi du nom de l'ex�cutable qui va recueillir les entr�es de journal sur son entr�e standard. Apache va lancer le processus de redirection des journaux au moment du d�marrage du serveur, et le relancera s'il cesse de fonctionner pendant l'ex�cution du serveur. (Nous d�nommons cette technique "journalisation redirig�e fiable" gr�ce � cette derni�re fonctionnalit�.)

Les processus de journalisation redirig�e sont lanc�s par le processus httpd parent, et h�ritent de l'UID de ce dernier. Cela signifie que les programmes de journalisation dirig�e s'ex�cutent g�n�ralement en tant que root. Il est donc tr�s important que ces programmes soient simples et s�curis�s.

Un des grands avantages de la journalisation redirig�e est la possibilit� d'effectuer la rotation des journaux sans avoir � red�marrer le serveur. Pour accomplir cette t�che, le serveur HTTP Apache fournit un programme simple appel� rotatelogs. Par exemple, pour une rotation des journaux toutes les 24 heures, ajoutez ces lignes :

Notez que l'ensemble de la commande qui sera appel�e par le tube de communication a �t� plac�e entre guillemets. Cet exemple concerne le journal des acc�s, mais la m�me technique peut �tre utilis�e pour le journal des erreurs.

Il existe un autre programme de rotation des journaux similaire mais beaucoup plus souple : il s'agit de "cronolog", non fourni par Apache, mais disponible ici.

Comme la journalisation conditionnelle, la journalisation redirig�e est un outil tr�s puissant, mais si elle existe, il est pr�f�rable d'utiliser une solution plus simple comme le traitement a posteriori hors ligne.

Par d�faut, le processus de redirection du journal est lanc� en invoquant un shell(en g�n�ral avec /bin/sh -c). Selon les sp�cificit�s du shell, l'invocation via un shell peut g�n�rer un processus shell suppl�mentaire pour toute la dur�e du programme de redirection du journal, et induire des probl�mes de gestion de signaux au cours du red�marrage.

Pour lancer le programme sans invoquer un shell, utilisez "||" au lieu de "|" :

H�tes virtuels

Lorsqu'un serveur poss�de plusieurs h�tes virtuels, il existe de nombreuses solutions pour g�rer les fichiers journaux. Par exemple, on peut utiliser les journaux comme s'il s'agissait d'un serveur avec un seul h�te. Il suffit pour cela de placer les directives de journalisation en dehors des sections <VirtualHost> au niveau du serveur principal, ce qui a pour effet de journaliser toutes les requ�tes dans le m�me journal des acc�s et des erreurs. Cette technique est cependant inappropri�e pour recueillir des statistiques sur chaque h�te virtuel individuellement.

Si des directives CustomLog ou ErrorLog sont plac�es dans une section <VirtualHost>, toutes les requ�tes ou erreurs pour cet h�te virtuel ne seront enregistr�es que dans le fichier sp�cifi�. Tout h�te virtuel qui ne poss�de pas de directives de journalisation verra ses requ�tes enregistr�es dans le journal du serveur principal. Cette technique est appropri�e pour un petit nombre d'h�tes virtuels, mais si ce nombre est important, elle peut devenir compliqu�e � g�rer. En outre, des probl�mes de nombre de descripteurs de fichiers insuffisant peuvent rapidement appara�tre.

Il existe un tr�s bon compromis pour le journal des acc�s. En int�grant les informations � propos de l'h�te virtuel � la cha�ne de format du journal, il est possible de journaliser tous les h�tes dans le m�me journal, puis de s�parer ult�rieurement le journal en plusieurs journaux individuels. Consid�rons par exemple les directives suivantes :

Le champ %v sert � enregistrer le nom de l'h�te virtuel qui traite la requ�te. Un programme tel que split-logfile peut ensuite �tre utilis� pour g�n�rer "� froid" autant de journaux que d'h�tes virtuels.

Autres fichiers journaux

Enregistrement du nombre r�el d'octets envoy�s et re�us

Le module mod_logio fournit deux champs LogFormat suppl�mentaires (%I et %O) qui permettent d'enregistrer le nombre r�el d'octets re�us et envoy�s sur le r�seau.

Journalisation de style investigation judiciaire (forensic logging)

Le module mod_log_forensic permet la journalisation � des fins d'investigation judiciaire des requ�tes des clients. La journalisation est effectu�e avant et apr�s le traitement de la requ�te, qui fait donc l'objet de deux entr�es dans le journal. Le g�n�rateur de journaux d'investigation est tr�s strict et ne permet aucune personnalisation. C'est un inestimable outil de d�bogage et de s�curit�.

Fichier PID

Au d�marrage, le d�mon httpd Apache enregistre l'identifiant du processus httpd parent dans le fichier logs/httpd.pid. Le nom de ce fichier peut �tre modifi� � l'aide de la directive PidFile. Cet identifiant permet � l'administrateur de red�marrer et arr�ter le d�mon en envoyant des signaux au processus parent ; sous Windows, vous devez utiliser l'option de ligne de commande -k. Pour plus de d�tails, consulter la page Arr�t et red�marrage.

Journal des scripts

Afin de faciliter le d�bogage, la directive ScriptLog vous permet d'enregistrer les entr�es et sorties des scripts CGI. Elle ne doit �tre utilis�e que pendant la phase de test, et en aucun cas sur un serveur en production. Vous trouverez plus d'informations dans la documentation du module mod_cgi.

Journal de r��criture

Lorsqu'on utilise les fonctionnalit�s puissantes et complexes du module mod_rewrite, il est presque toujours n�cessaire d'utiliser la directive RewriteLog afin de faciliter le d�bogage. Ce fichier journal fournit une analyse d�taill�e de la transformation des requ�tes par le moteur de r��criture. Le niveau de d�tail est contr�l� par la directive RewriteLogLevel.