2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
4 <!-- English Revision: 1674195:1780210 (outdated) -->
5 <!-- French translation : Lucien GENTIS -->
6 <!-- Reviewed by : Vincent Deffontaines -->
9 Licensed to the Apache Software Foundation (ASF) under one or more
10 contributor license agreements. See the NOTICE file distributed with
11 this work for additional information regarding copyright ownership.
12 The ASF licenses this file to You under the Apache License, Version 2.0
13 (the "License"); you may not use this file except in compliance with
14 the License. You may obtain a copy of the License at
16 http://www.apache.org/licenses/LICENSE-2.0
18 Unless required by applicable law or agreed to in writing, software
19 distributed under the License is distributed on an "AS IS" BASIS,
20 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
21 See the License for the specific language governing permissions and
22 limitations under the License.
25 <modulesynopsis metafile="mod_cache.xml.meta">
27 <name>mod_cache</name>
28 <description>Filtre de mise en cache HTTP conforme à la RFC 2616</description>
29 <status>Extension</status>
30 <sourcefile>mod_cache.c</sourcefile>
31 <identifier>cache_module</identifier>
34 <note type="warning">Ce module doit être utilisé avec précautions
35 car lorsque la directive <directive
36 module="mod_cache">CacheQuickHandler</directive> est définie à sa
37 valeur par défaut <strong>on</strong>, les directives <directive
38 module="mod_access_compat">Allow</directive> and <directive
39 module="mod_access_compat">Deny</directive> sont court-circuitées. Vous
40 ne devez donc pas activer la gestion rapide de la mise en cache pour
41 un contenu auquel vous souhaitez limiter l'accès en fonction du nom
42 d'hôte du client, de l'adresse IP ou d'une variable
43 d'environnement.</note>
45 <p><module>mod_cache</module> implémente un <strong>filtre de mise
46 en cache de contenu HTTP</strong> conforme à la <a
47 href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a>, avec
48 support de la mise en cache des réponses dont le contenu a été
49 négocié et comportant l'en-tête Vary.</p>
51 <p>La mise en cache conforme à la RFC 2616 fournit un mécanisme
52 permettant de vérifier si un contenu expiré ou dépassé est encore à
53 jour, et peut apporter un gain de performances significatif si le
54 serveur original supporte les <strong>requêtes
55 conditionnelles</strong> en prenant en compte l'en-tête de requête
57 href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">If-None-Match</a>.
58 Le contenu n'est ainsi régénéré que lorsqu'il a été modifié, et non
59 lorsqu'il a expiré.</p>
61 <p>En tant que filtre, <module>mod_cache</module> peut être placé
62 en face d'un contenu issu de tout gestionnaire, y compris
63 <strong>des fichiers à accès séquentiel</strong> (servis depuis un
65 cache sur un gros disque), la sortie d'un <strong>script
66 CGI</strong> ou d'un <strong>générateur de contenu
67 dynamique</strong>, ou du contenu <strong>mandaté depuis un autre
70 <p>Dans la configuration par défaut, <module>mod_cache</module>
71 place le filtre de mise en cache aussi loin que possible dans la
72 pile de filtres, utilisant le <strong>gestionnaire rapide</strong>
73 pour court-circuiter tout traitement par requête lors de l'envoi du
74 contenu au client. Dans ce mode opératoire,
75 <module>mod_cache</module> peut être considéré comme un serveur
76 mandataire avec cache fixé en tête du serveur web, alors qu'il
77 s'exécute dans ce même serveur web.</p>
79 <p>Lorsque le gestionnaire rapide est désactivé via la directive
80 <directive module="mod_cache">CacheQuickHandler</directive>, il
81 devient possible d'insérer le filtre <strong>CACHE</strong> à un
82 point de la pile de filtres choisi par l'administrateur. Ceci permet
83 de mettre en cache un contenu avant que celui-ci ne soit
84 personnalisé par le filtre <module>mod_include</module>, ou
85 éventuellement compressé par le filtre <module>mod_deflate</module>.</p>
87 <p>Dans le mode de fonctionnement normal, <module>mod_cache</module>
88 peut être contrôlé par les en-têtes <a
89 href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">Cache-Control</a>
91 href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32">Pragma</a>
92 envoyés par un client dans une requête, ou par un serveur dans une
93 réponse. Dans des circonstances exceptionnelles,
94 <module>mod_cache</module> peut cependant être configuré pour
95 outrepasser ces en-têtes et forcer un comportement spécifique au
96 site, bien qu'un tel comportement sera limité à ce cache seulement,
97 et n'affectera pas les opérations des autres caches qui peuvent
98 s'insérer entre le client et le serveur, et ce type de configuration
99 ne doit donc être utiliser qu'en cas de nécessité absolue.</p>
101 <p>La RFC 2616 permet au cache de renvoyer des données périmées
102 pendant que l'entrée périmée correspondante est mise à jour depuis
103 le serveur original, et <module>mod_cache</module> supporte cette
104 fonctionnalité lorsque la directive <directive
105 module="mod_cache">CacheLock</directive> est configurée en
106 conséquence. De telles réponses comportent un en-tête HTTP <a
107 href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a>
108 contenant un code de réponse 110. La RFC 2616 permet aussi au cache
109 de renvoyer des données périmées lorsque la tentative de mise à jour
110 des données périmées renvoie une erreur 500 ou supérieure, et cette
111 fonctionnalité est supportée par défaut par
112 <module>mod_cache</module>. De telles réponses comportent un en-tête HTTP <a
113 href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a>
114 contenant un code de réponse 111.</p>
116 <p><module>mod_cache</module> requiert les services d'un ou
117 plusieurs modules de gestion de stockage. La distribution Apache de base
118 inclut les modules de gestion de stockage suivants :</p>
120 <dt><module>mod_cache_disk</module></dt>
122 <dd>implémente un gestionnaire de stockage sur disque. Les en-têtes
123 et corps sont stockés séparément sur le disque dans une structure de
124 répertoires basée sur le condensé md5 de l'URL mise en cache.
125 Plusieurs réponses à contenu négocié peuvent être stockées en même
126 temps, mais la mise en cache de contenus partiels n'est pas
127 supportée par ce module. L'utilitaire
128 <program>htcacheclean</program> permet de lister et de supprimer les
129 URLs mises en cache, et de maintenir le cache en deçà de
130 certaines limites de taille et de nombre d'inodes.</dd>
131 <dt><module>mod_cache_socache</module></dt>
132 <dd>Implémente un gestionnaire de stockage basé sur un cache d'objets
133 partagés. Les en-têtes et corps sont stockés ensemble sous une seule
134 clé basée sur l'URL de la réponse mise en cache. Des réponses à
135 contenus multiples négociés peuvent être stockées simultanément, mais
136 ce module ne supporte pas la mise en cache de contenus partiels.</dd>
139 <p>Pour de plus amples détails, une description, et des exemples,
140 reportez-vous au <a href="../caching.html">Guide de la mise en
143 <seealso><a href="../caching.html">Guide de la mise en
146 <section id="related"><title>Modules apparentés et directives</title>
149 <module>mod_cache_socache</module>
152 <directive module="mod_cache_disk">CacheRoot</directive>
153 <directive module="mod_cache_disk">CacheDirLevels</directive>
154 <directive module="mod_cache_disk">CacheDirLength</directive>
155 <directive module="mod_cache_disk">CacheMinFileSize</directive>
156 <directive module="mod_cache_disk">CacheMaxFileSize</directive>
157 <directive module="mod_cache_socache">CacheSocache</directive>
158 <directive module="mod_cache_socache">CacheSocacheMaxTime</directive>
159 <directive module="mod_cache_socache">CacheSocacheMinTime</directive>
160 <directive module="mod_cache_socache">CacheSocacheMaxSize</directive>
161 <directive module="mod_cache_socache">CacheSocacheReadSize</directive>
162 <directive module="mod_cache_socache">CacheSocacheReadTime</directive>
167 <section id="sampleconf"><title>Exemple de configuration</title>
168 <example><title>Extrait de httpd.conf</title>
169 <highlight language="config">
171 # Exemple de configuration du cache
173 LoadModule cache_module modules/mod_cache.so
174 <IfModule mod_cache.c>
175 LoadModule cache_disk_module modules/mod_cache_disk.so
176 <IfModule mod_cache_disk.c>
177 CacheRoot c:/cacheroot
183 # Lorsqu'on sert de mandataire, on ne met pas en cache la liste
184 # des mises à jour de sécurité
185 CacheDisable http://security.update.server/update-list/
191 <section id="thunderingherd"><title>Eviter une tempête de requête</title>
192 <p>Lorsqu'une entrée du cache est périmée, <module>mod_cache</module>
193 soumet une requête conditionnelle au processus d'arrière-plan, qui est
194 censé confirmer la validité de l'entrée du cache, ou dans la négative
195 envoyer une entrée mise à jour.</p>
196 <p>Un court mais non négligeable laps de temps existe entre le moment
197 où l'entrée du cache est périmée, et le moment où elle est mise à
198 jour. Sur un serveur fortement chargé, un certain nombre de requêtes
199 peut arriver pendant ce laps de temps, et provoquer une
200 <strong>tempête</strong> de requêtes susceptibles de saturer le
201 processus d'arrière-plan de manière soudaine et imprédictible.</p>
202 <p>Pour contenir cette tempête, on peut utiliser la directive
203 <directive>CacheLock</directive> afin de définir un répertoire où
204 seront créés <strong>à la volée</strong> des verrous pour les URLs.
205 Ces verrous sont utilisés comme autant d'<strong>indications</strong>
206 par les autres requêtes, soit pour empêcher une tentative de mise en
207 cache (un autre processus est en train de récupérer l'entité), soit
208 pour indiquer qu'une entrée périmée est en cours de mise à jour
209 (pendant ce temps, c'est le contenu périmé qui sera renvoyé).
212 <title>Mise en cache initiale d'une entrée</title>
213 <p>Lorsqu'une entité est mise en cache pour la première fois, un
214 verrou est créé pour cette entité jusqu'à ce que la réponse ait été
215 entièrement mise en cache. Pendant la durée de vie du verrou, le
216 cache va empêcher une seconde tentative de mise en cache de la même
217 entité. Bien que cela ne suffise pas à contenir la tempête de
218 requêtes, toute tentative de mettre en cache la même entité
219 plusieurs fois simultanément est stoppée.
223 <title>Mise à jour d'une entrée périmée</title>
224 <p>Lorsqu'une entrée atteint la limite de sa durée de vie, et
225 devient par conséquent périmée, un verrou est créé pour cette entité
226 jusqu'à ce que la réponse ait été soit confirmée comme encore
227 valide, soit remplacée par le processus d'arrière-plan. Pendant la
228 durée de vie du verrou, une seconde requête entrante va provoquer le
229 renvoi de la donnée périmée, et la tempête de requêtes sera
233 <title>Verrous et en-tête Cache-Control: no-cache</title>
234 <p>Les verrous ne sont utilisés <strong>qu'à titre
235 indicatif</strong> pour enjoindre le cache à être plus coopératif
236 avec les serveurs d'arrière-plan, et il est possible de passer outre
237 si nécessaire. Si le client envoie une requête contenant un en-tête
238 Cache-Control imposant un nouveau téléchargement de l'entité, tout
239 verrou éventuel sera ignoré, la requête du client sera honorée
240 immédiatement, et l'entrée du cache mise à jour.</p>
242 <p>Comme mécanisme de sécurité supplémentaire, la durée de vie
243 maximale des verrous est configurable. Lorsque cette limite est
244 atteinte, le verrou est supprimé et une autre requête peut alors en
245 créer un nouveau. Cette durée de vie peut être définie via la
246 directive <directive>CacheLockMaxAge</directive>, et sa valeur par
247 défaut est de 5 secondes.
251 <title>Exemple de configuration</title>
252 <example><title>Activation du verrouillage du cache</title>
253 <highlight language="config">
255 # Active le verrouillage du cache
257 <IfModule mod_cache.c>
259 CacheLockPath /tmp/mod_cache-lock
267 <section id="finecontrol"><title>Contrôle fin via le filtre CACHE</title>
268 <p>Dans son mode de fonctionnement par défaut, le cache s'exécute sous
269 la forme d'un gestionnaire rapide, court-circuitant la majorité des
270 traitements du serveur et fournissant ainsi une mise en cache
271 possédant les plus hautes performances disponibles.</p>
273 <p>Dans ce mode, le cache <strong>s'incruste</strong> devant le
274 serveur, comme si un mandataire de mise en cache indépendant RFC 2616
275 était placé devant ce dernier.</p>
277 <p>Bien que que ce mode offre les meilleures performances, les
278 administrateurs peuvent souhaiter, dans certaines circonstances,
279 effectuer des traitements sur la requête après que cette dernière ait
280 été mise en cache, comme ajouter du contenu personnalisé à la page
281 mise en cache, ou appliquer des restrictions d'autorisations au
282 contenu. Pour y parvenir, l'administrateur sera alors souvent forcé de
283 placer des serveurs mandataires inverses indépendants soit derrière,
284 soit devant le serveur de mise en cache.</p>
286 <p>Pour résoudre ce problème, la directive <directive
287 module="mod_cache">CacheQuickHandler</directive> peut être définie à
288 <strong>off</strong>, afin que le serveur traite toutes les phases
289 normalement exécutées par une requête non mise en cache, y compris les
290 phases <strong>d'authentification et d'autorisation</strong>.</p>
292 <p>En outre, l'administrateur peut éventuellement spécifier le
293 <strong>point précis dans la chaîne de filtrage</strong> où devra
294 intervenir la mise en cache en ajoutant le filtre
295 <strong>CACHE</strong> à la chaîne de filtrage en sortie.</p>
297 <p>Par exemple, pour mettre en cache le contenu avant d'appliquer une
298 compression à la réponse, placez le filtre <strong>CACHE</strong>
299 avant le filtre <strong>DEFLATE</strong> comme dans l'exemple suivant
302 <highlight language="config">
303 # Mise en cache du contenu avant la compression optionnelle
304 CacheQuickHandler off
305 AddOutputFilterByType CACHE;DEFLATE text/plain
308 <p>Une autre possibilité consiste à mettre en cache le contenu avant
309 l'ajout de contenu personnalisé via <module>mod_include</module> (ou
310 tout autre filtre de traitement de contenu). Dans l'exemple suivant,
311 les modèles contenant des balises comprises par
312 <module>mod_include</module> sont mis en cache avant d'être
313 interprétés :</p>
315 <highlight language="config">
316 # Mise en cache du contenu avant l'intervention de mod_include et
318 CacheQuickHandler off
319 AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html
322 <p>Vous pouvez insérer le filtre <strong>CACHE</strong> en tout point
323 de la chaîne de filtrage. Dans l'exemple suivant, le contenu est mis
324 en cache après avoir été interprété par <module>mod_include</module>,
325 mais avant d'être traité par <module>mod_deflate</module> :</p>
327 <highlight language="config">
328 # Mise en cache du contenu entre les interventions de mod_include et
330 CacheQuickHandler off
331 AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html
334 <note type="warning"><title>Avertissement :</title>Si pour une raison
335 ou pour une autre, le point d'insertion du filtre
336 <strong>CACHE</strong> dans la chaîne de filtrage est modifié, vous
337 devez <strong>vider votre cache</strong> pour être sûr que les données
338 servies soient à jour. En effet, <module>mod_cache</module> n'est pas
339 en mesure d'effectuer cette opération à votre place.</note>
343 <section id="status"><title>Etat du cache et journalisation</title>
344 <p>Lorsque <module>mod_cache</module> a décidé s'il devait ou non
345 servir une entité depuis le cache, les raisons précises de cette
346 décision sont enregistrées dans l'environnement du sous-processus
347 interne à la requête sous la clé <strong>cache-status</strong>.
348 Cette information peut être journalisée via la directive <directive
349 module="mod_log_config">LogFormat</directive> comme suit :</p>
351 <highlight language="config">
352 LogFormat "%{cache-status}e ..."
355 <p>En fonction de la décision prise, l'information est aussi écrite
356 dans l'environnement du sous-processus sous une des quatre clés
360 <dt>cache-hit</dt><dd>Le contenu a été servi depuis le cache.</dd>
361 <dt>cache-revalidate</dt><dd>Le contenu du cache était périmé, a été
362 mis à jour avec succès, puis servi depuis le cache.</dd>
363 <dt>cache-miss</dt><dd>Le contenu n'était pas dans le cache et a été
364 servi directement depuis le serveur demandé.</dd>
365 <dt>cache-invalidate</dt><dd>L'entité du cache est devenue invalide
366 suite à une requête d'un type autre que GET ou HEAD.</dd>
369 <p>Il est alors possible d'envisager une journalisation conditionnelle
370 du traitement des requêtes par rapport au cache comme dans l'exemple
373 <highlight language="config">
374 CustomLog "cached-requests.log" common env=cache-hit
375 CustomLog "uncached-requests.log" common env=cache-miss
376 CustomLog "revalidated-requests.log" common env=cache-revalidate
377 CustomLog "invalidated-requests.log" common env=cache-invalidate
380 <p>Pour les concepteurs de modules, une accroche (hook) nommée
381 <var>cache_status</var> est disponible et permet aux modules de
382 répondre aux résultats de la vérification du cache ci-dessus de manière
383 personnalisée.</p>
388 <name>CacheEnable</name>
389 <description>Active la mise en cache des URLs spécifiées en utilisant le
390 gestionnaire de stockage précisé</description>
391 <syntax>CacheEnable <var>type de cache</var> [<var>chaîne
393 <contextlist><context>server config</context><context>virtual host</context>
394 <context>directory</context>
396 <compatibility>Une chaîne URL telle que '/' s'appliquait à tout contenu
397 en mandat direct dans les versions 2.2 et antérieures.</compatibility>
400 <p>La directive <directive>CacheEnable</directive> enjoint
401 <module>mod_cache</module> de mettre en cache l'URL précisée par
402 <var>chaîne URL</var>, ainsi que les URLs de niveaux inférieurs. Le
403 gestionnaire de stockage du cache est spécifié à l'aide de
404 l'argument <var>type de cache</var>. La directive
405 <directive>CacheEnable</directive> peut être placée à l'intérieur d'une
406 section <directive type="section">Location</directive> ou <directive
407 type="section">LocationMatch</directive> pour indiquer que le
408 contenu considéré peut être mis en cache. Si <var>type de cache</var>
409 a pour valeur <code>disk</code>, <module>mod_cache</module>
410 utilisera le gestionnaire de stockage sur disque implémenté par
411 <module>mod_cache_disk</module>. Pour que <module>mod_cache</module>
412 utilise le gestionnaire de stockage basé sur le cache d'objets
413 partagés implémenté par <module>mod_cache_socache</module>,
414 spécifiez <code>socache</code> comme valeur du paramètre <var>type
416 <p>Si les différentes directives <directive>CacheEnable</directive>
417 spécifient des URLs qui se recoupent (comme dans l'exemple
418 ci-dessous), tous les gestionnaires de stockage possibles seront
419 lancés, jusqu'au premier d'entre eux qui traitera effectivement la
421 L'ordre dans lequel les gestionnaires de stockage sont lancés est
422 déterminé par l'ordre dans lequel apparaissent les directives
423 <directive>CacheEnable</directive> dans le fichier de
424 configuration. Les directives <directive>CacheEnable</directive>
425 situées à l'intérieur de sections <directive
426 type="section">Location</directive> ou <directive
427 type="section">LocationMatch</directive> sont traitées avant les
428 directives <directive>CacheEnable</directive> définies au niveau
431 <p>En fonctionnement du type serveur mandataire direct, <var>chaîne
432 URL</var> doit au moins débuter par un protocole pour lequel la mise
433 en cache doit être activée.</p>
435 <highlight language="config">
436 # Mise en cache de contenu (gestionnaire normal seulement)
437 CacheQuickHandler off
438 <Location "/foo">
442 # Mise en cache via une expression rationnelle (gestionnaire normal seulement)
443 CacheQuickHandler off
444 <LocationMatch "foo$">
446 </LocationMatch>
448 # Mise en cache de tous les contenus, à l'exception des URLs
449 # mandatées en direct (gestionnaire normal ou rapide)
452 # Mise en cache des URLs FTP mandatées (gestionnaire normal ou rapide)
453 CacheEnable disk ftp://
455 # Mise en cache des contenus mandatés en direct depuis www.example.org (gestionnaire normal ou rapide)
456 CacheEnable disk http://www.example.org/
459 <p>Un nom d'hôte commençant par un caractère <strong>"*"</strong>
460 correspondra à tout nom d'hôte se terminant par le suffixe
461 considéré. Un nom d'hôte commençant par un caractère
462 <strong>"."</strong> correspondra à tout nom d'hôte contenant le
463 composant de nom de domaine qui suit ce caractère.</p>
465 <highlight language="config">
466 # Correspond à www.example.org et fooexample.org
467 CacheEnable disk http://*example.org/
468 # Correspond à www.example.org, mais pas à fooexample.org
469 CacheEnable disk http://.example.org/
472 <p>Depuis la version 2.2.12, on peut définir la variable
473 d'environnement <code>no-cache</code> pour une définition plus fine
474 des ressources à mettre en cache.</p>
477 <seealso><a href="../env.html">Les variables d'environnement dans
482 <name>CacheDisable</name>
483 <description>Désactive la mise en cache des URLs
484 spécifiées</description>
485 <syntax>CacheDisable <var>chaîne-url</var> | <var>on</var></syntax>
486 <contextlist><context>server config</context><context>virtual host</context>
487 <context>directory</context><context>.htaccess</context>
491 <p>La directive <directive>CacheDisable</directive> enjoint
492 <module>mod_cache</module> de <em>ne pas</em> mettre en cache l'URL
493 spécifiée par <var>chaîne URL</var>, ainsi que les URLs de niveaux
494 inférieurs.</p>
496 <example><title>Exemple</title>
497 <highlight language="config">
498 CacheDisable /fichiers_locaux
502 <p>Si la directive se trouve à l'intérieur d'une section <directive
503 type="section">Location</directive>, le chemin doit être spécifié en
504 dessous de la Location, et si le mot "on" est utilisé, la mise en
505 cache sera désactivée pour l'ensemble de l'arborescence concernée
506 par la section Location.</p>
508 <example><title>Exemple</title>
509 <highlight language="config">
510 <Location "/foo">
516 <p>Avec les versions 2.2.12 et ultérieures, on peut définir la
517 variable d'environnement <code>no-cache</code> pour une définition
518 plus fine des ressources à mettre en cache.</p>
520 <seealso><a href="../env.html">Les variables d'environnement dans
524 <name>CacheMaxExpire</name>
525 <description>La durée maximale en secondes de mise en cache d'un
526 document</description>
527 <syntax>CacheMaxExpire <var>secondes</var></syntax>
528 <default>CacheMaxExpire 86400 (une journée)</default>
529 <contextlist><context>server config</context><context>virtual host</context>
530 <context>directory</context><context>.htaccess</context>
534 <p>La directive <directive>CacheMaxExpire</directive> permet de
535 spécifier le nombre maximum de secondes pendant lequel les documents
536 HTTP suceptibles d'être mis en cache seront conservés sans vérifier
537 leur contenu sur le serveur d'origine. Ce nombre de secondes
538 correspond donc à la durée maximale pendant laquelle un document ne
539 sera pas à jour. L'utilisation de cette valeur maximale est forcée,
540 même si le document possède une date d'expiration.</p>
542 <highlight language="config">
543 CacheMaxExpire 604800
550 <name>CacheMinExpire</name>
551 <description>La durée minimale en secondes de mise en cache d'un
552 document</description>
553 <syntax>CacheMinExpire <var>secondes</var></syntax>
554 <default>CacheMinExpire 0</default>
555 <contextlist><context>server config</context><context>virtual host</context>
556 <context>directory</context><context>.htaccess</context>
560 <p>La directive <directive>CacheMaxExpire</directive> permet de
561 spécifier le nombre maximum de secondes pendant lequel les documents
562 HTTP suceptibles d'être mis en cache seront conservés sans vérifier
563 leur contenu sur le serveur d'origine. Elle n'est prise en compte
564 que dans le cas où le document ne possède aucune date d'expiration
567 <highlight language="config">
574 <name>CacheDefaultExpire</name>
575 <description>La durée par défaut de mise en cache d'un document
576 lorsqu'aucune date d'expiration n'a été spécifiée.</description>
577 <syntax>CacheDefaultExpire <var>secondes</var></syntax>
578 <default>CacheDefaultExpire 3600 (une heure)</default>
579 <contextlist><context>server config</context><context>virtual host</context>
580 <context>directory</context><context>.htaccess</context>
584 <p>La directive <directive>CacheDefaultExpire</directive> permet de
585 spécifier un temps par défaut, en secondes, pendant lequel sera
586 conservé dans le cache un document qui ne possède ni date
587 d'expiration, ni date de dernière modification. La valeur de cette
588 directive est écrasée par la valeur de la directive
589 <directive>CacheMaxExpire</directive> si cette dernière est
592 <highlight language="config">
593 CacheDefaultExpire 86400
599 <name>CacheIgnoreNoLastMod</name>
600 <description>Ignore le fait qu'une réponse ne possède pas d'en-tête Last
601 Modified.</description>
602 <syntax>CacheIgnoreNoLastMod On|Off</syntax>
603 <default>CacheIgnoreNoLastMod Off</default>
604 <contextlist><context>server config</context><context>virtual host</context>
605 <context>directory</context><context>.htaccess</context>
609 <p>Normalement, les documents qui ne possèdent pas de date de
610 dernière modification ne sont pas mis en cache. Dans certaines
611 circonstances, la date de dernière modification est supprimée (au
612 cours des traitements liés à <module>mod_include</module> par
613 exemple), ou n'existe tout simplement pas. La directive
614 <directive>CacheIgnoreNoLastMod</directive> permet de spécifier si
615 les documents ne possèdant pas de date de dernière modification
616 doivent être mis en cache, même sans date de dernière modification.
617 Si le document ne possède ni date d'expiration, ni date de dernière
618 modification, la valeur spécifiée par la directive
619 <directive>CacheDefaultExpire</directive> servira à générer une date
623 <highlight language="config">
624 CacheIgnoreNoLastMod On
630 <name>CacheIgnoreCacheControl</name>
631 <description>Ignore les en-têtes de requête enjoignant de ne pas servir
632 le contenu au client depuis le cache</description>
633 <syntax>CacheIgnoreCacheControl On|Off</syntax>
634 <default>CacheIgnoreCacheControl Off</default>
635 <contextlist><context>server config</context><context>virtual host</context>
639 <p>Normalement, les requêtes contenant des en-têtes tels que
640 Cache-Control: no-cache ou Pragma: no-cache ne sont pas servies
641 depuis le cache. La directive
642 <directive>CacheIgnoreCacheControl</directive> permet de modifier ce
643 comportement. Avec <directive>CacheIgnoreCacheControl
644 On</directive>, le serveur tentera de servir la ressource depuis le
645 cache, même si la requête contient un en-tête
648 <highlight language="config">
649 CacheIgnoreCacheControl On
652 <note type="warning"><title>Avertissement :</title>
653 Cette directive permet de servir des ressources depuis le cache,
654 même si le client a demandé à ce qu'il n'en soit pas ainsi. Le
655 contenu servi est ainsi susceptible d'être périmé.
658 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
659 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
663 <name>CacheIgnoreQueryString</name>
664 <description>Ignore la chaîne de paramètres lors de la mise en
666 <syntax>CacheIgnoreQueryString On|Off</syntax>
667 <default>CacheIgnoreQueryString Off</default>
668 <contextlist><context>server config</context><context>virtual host</context>
672 <p>Normalement, les requêtes comportant une chaîne de paramètres
673 sont mises en cache séparément si leurs chaînes de paramètres
675 En accord avec la RFC 2616/13.9, cette mise en cache n'est effectuée
676 séparément que si une date d'expiration est spécifiée. La directive
677 <directive>CacheIgnoreQueryString</directive> permet la mise en
678 cache de requêtes même si aucune date d'expiration est spécifiée, et
679 de renvoyer une réponse depuis la cache même si les chaînes de
680 paramètres diffèrent. Du point de vue du cache, la requête est
681 traitée comme si elle ne possèdait pas de chaîne de paramètres
682 lorsque cette directive est activée.</p>
684 <highlight language="config">
685 CacheIgnoreQueryString On
692 <name>CacheLastModifiedFactor</name>
693 <description>Le facteur utilisé pour générer une date d'expiration en
694 fonction de la date de dernière modification.</description>
695 <syntax>CacheLastModifiedFactor <var>flottant</var></syntax>
696 <default>CacheLastModifiedFactor 0.1</default>
697 <contextlist><context>server config</context><context>virtual host</context>
698 <context>directory</context><context>.htaccess</context>
702 <p>Si un document ne possède pas de date d'expiration, elle peut
703 être calculée en fonction de la date de dernière modification, si
704 elle existe. La directive
705 <directive>CacheLastModifiedFactor</directive> permet de spécifier
706 un <var>facteur</var> à utiliser pour la génération de cette date
707 d'expiration au sein de la formule suivante :
709 <code>délai-expiration = durée-depuis-date-dernière-modification *
711 date-expiration = date-courante + délai-expiration</code>
713 Par exemple, si la dernière modification du document date de 10
714 heures, et si <var>facteur</var> a pour valeur 0.1, le délai
715 d'expiration sera de 10*0.1 = 1 heure. Si l'heure courante est
716 3:00pm, la date d'expiration calculée sera 3:00pm + 1 heure =
719 Si le délai d'expiration est supérieur à celui spécifié par la
720 directive <directive>CacheMaxExpire</directive>, c'est ce dernier
723 <highlight language="config">
724 CacheLastModifiedFactor 0.5
730 <name>CacheIgnoreHeaders</name>
731 <description>Ne pas stocker le(s) en-tête(s) spécifié(s) dans le cache.
733 <syntax>CacheIgnoreHeaders <var>en-tête</var> [<var>en-tête</var>] ...</syntax>
734 <default>CacheIgnoreHeaders None</default>
735 <contextlist><context>server config</context><context>virtual host</context>
739 <p>En accord avec la RFC 2616, les en-têtes HTTP hop-by-hop ne sont
740 pas stockés dans le cache. Les en-têtes HTTP suivant sont des
741 en-têtes hop-by-hop, et en tant que tels, ne sont en <em>aucun</em>
742 cas stockés dans le cache, quelle que soit la définition de la
743 directive <directive>CacheIgnoreHeaders</directive> :</p>
746 <li><code>Connection</code></li>
747 <li><code>Keep-Alive</code></li>
748 <li><code>Proxy-Authenticate</code></li>
749 <li><code>Proxy-Authorization</code></li>
750 <li><code>TE</code></li>
751 <li><code>Trailers</code></li>
752 <li><code>Transfer-Encoding</code></li>
753 <li><code>Upgrade</code></li>
756 <p>La directive <directive>CacheIgnoreHeaders</directive> permet de
757 spécifier quels en-têtes HTTP ne doivent pas être stockés dans le
758 cache. Par exemple, il peut s'avérer pertinent dans certains cas de
759 ne pas stocker les cookies dans le cache.</p>
761 <p>La directive <directive>CacheIgnoreHeaders</directive> accepte
762 une liste d'en-têtes HTTP séparés par des espaces, qui ne doivent
763 pas être stockés dans le cache. Si les en-têtes hop-by-hop sont les
764 seuls à ne pas devoir être stockés dans le cache (le comportement
765 compatible RFC 2616), la directive
766 <directive>CacheIgnoreHeaders</directive> peut être définie à
767 <code>None</code>.</p>
769 <example><title>Exemple 1</title>
770 <highlight language="config">
771 CacheIgnoreHeaders Set-Cookie
775 <example><title>Exemple 2</title>
776 <highlight language="config">
777 CacheIgnoreHeaders None
781 <note type="warning"><title>Avertissement :</title>
782 Si des en-têtes nécessaires à la bonne gestion du cache, comme
783 <code>Expires</code>, ne sont pas stockés suite à la définition
784 d'une directive <directive>CacheIgnoreHeaders</directive>, le
785 comportement de mod_cache sera imprévisible.
791 <name>CacheIgnoreURLSessionIdentifiers</name>
792 <description>Ignore les identifiants de session définis encodés dans
793 l'URL lors de la mise en cache
795 <syntax>CacheIgnoreURLSessionIdentifiers <var>identifiant</var>
796 [<var>identifiant</var>] ...</syntax>
797 <default>CacheIgnoreURLSessionIdentifiers None</default>
798 <contextlist><context>server config</context><context>virtual host</context>
802 <p>Certaines applications encodent l'identifiant de session dans
803 l'URL comme dans l'exemple suivant :
806 <li><code>/une-application/image.gif;jsessionid=123456789</code></li>
807 <li><code>/une-application/image.gif?PHPSESSIONID=12345678</code></li>
809 <p>Ceci implique la mise en cache des ressources séparément pour
810 chaque session, ce qui n'est en général pas souhaité. La directive
811 <directive>CacheIgnoreURLSessionIdentifiers</directive> permet de
812 définir une liste d'identifiants qui seront supprimés de la clé
813 utilisée pour identifier une entité dans le cache, de façon à ce que
814 les ressources ne soient pas stockées séparément pour chaque
817 <p><code>CacheIgnoreURLSessionIdentifiers None</code> vide la liste
818 des identifiants ignorés. Autrement, chaque identifiant spécifié est
819 ajouté à la liste.</p>
821 <example><title>Exemple 1</title>
822 <highlight language="config">
823 CacheIgnoreURLSessionIdentifiers jsessionid
827 <example><title>Exemple 2</title>
828 <highlight language="config">
829 CacheIgnoreURLSessionIdentifiers None
837 <name>CacheStoreExpired</name>
838 <description>Tente de mettre en cache les réponses que le serveur
839 considère comme arrivées à expiration</description>
840 <syntax>CacheStoreExpired On|Off</syntax>
841 <default>CacheStoreExpired Off</default>
842 <contextlist><context>server config</context><context>virtual host</context>
843 <context>directory</context><context>.htaccess</context>
847 <p>Depuis la version 2.2.4, les réponses qui sont arrivées à
848 expiration ne sont pas stockées dans le cache. La directive
849 <directive>CacheStoreExpired</directive> permet de modifier ce
850 comportement. Avec <directive>CacheStoreExpired</directive> On, le
851 serveur tente de mettre en cache la ressource si elle est périmée.
852 Les requêtes suivantes vont déclencher une requête si-modifié-depuis
853 de la part du serveur d'origine, et la réponse sera renvoyée à
854 partir du cache si la ressource d'arrière-plan n'a pas été modifiée.</p>
856 <highlight language="config">
864 <name>CacheStorePrivate</name>
865 <description>Tente de mettre en cache des réponses que le serveur a
866 marquées comme privées</description>
867 <syntax>CacheStorePrivate On|Off</syntax>
868 <default>CacheStorePrivate Off</default>
869 <contextlist><context>server config</context><context>virtual host</context>
870 <context>directory</context><context>.htaccess</context>
874 <p>Normalement, les réponse comportant un en-tête Cache-Control:
875 dont la valeur est private ne seront pas stockées dans le cache. La
876 directive <directive>CacheStorePrivate</directive> permet de
877 modifier ce comportement. Si
878 <directive>CacheStorePrivate</directive> est définie à On, le
879 serveur tentera de mettre la ressource en cache, même si elle
880 contient un en-tête private.</p>
883 <highlight language="config">
888 <note type="warning"><title>Avertissement :</title>
889 Cette directive autorise la mise en cache même si le serveur
890 indique que la ressource ne doit pas être mise en cache. Elle
891 n'est de ce fait appropriée que dans le cas d'un cache
895 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
896 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
900 <name>CacheStoreNoStore</name>
901 <description>Tente de mettre en cache les requêtes ou réponses dont
902 l'entête Cache-Control: a pour valeur no-store.</description>
903 <syntax>CacheStoreNoStore On|Off</syntax>
904 <default>CacheStoreNoStore Off</default>
905 <contextlist><context>server config</context><context>virtual host</context>
906 <context>directory</context><context>.htaccess</context>
910 <p>Normalement, les requêtes ou réponses dont l'en-tête
911 Cache-Control: a pour valeur no-store ne sont pas stockées dans le
912 cache. La directive <directive>CacheStoreNoStore</directive> permet
913 de modifier ce comportement. Si
914 <directive>CacheStoreNoStore</directive> est définie à On, le
915 serveur tente de mettre la ressource en cache même si elle contient
916 un en-tête no-store.</p>
919 <highlight language="config">
924 <note type="warning"><title>Avertissement :</title>
925 Selon la RFC 2616, la valeur d'en-tête no-store est censée
926 "prévenir la suppression ou la rétention par inadvertance
927 d'informations sensibles (par exemple, sur des bandes de
928 sauvegarde)". Autrement dit, l'activation de la directive
929 <directive>CacheStoreNoCache</directive> pourrait provoquer le
930 stockage d'informations sensibles dans le cache. Vous avez donc
931 été prévenus.
934 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
935 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
939 <name>CacheLock</name>
940 <description>Active la protection contre les tempêtes de requêtes.</description>
941 <syntax>CacheLock <var>on|off</var></syntax>
942 <default>CacheLock off</default>
943 <contextlist><context>server config</context><context>virtual host</context>
947 <p>La directive <directive>CacheLock</directive> active la protection
948 contre les tempêtes de requêtes pour l'espace d'adressage donné.</p>
950 <p>La configuration minimale pour activer le verrouillage contre les
951 tempêtes de requêtes dans le répertoire par
952 défaut des fichiers run-time est
955 <highlight language="config">
956 # Active le verrouillage du cache
960 <p>Les verrous sont des fichiers vides qui n'existent que pour les
961 URLs présentes dont le contenu est périmé ; ils consomment dont bien
962 moins de ressources que le cache disque traditionnel.</p>
968 <name>CacheLockPath</name>
969 <description>Définit le répertoire des verrous.</description>
970 <syntax>CacheLockPath <var>répertoire</var></syntax>
971 <default>CacheLockPath mod_cache-lock</default>
972 <contextlist><context>server config</context><context>virtual host</context>
976 <p>La directive <directive>CacheLockPath</directive> permet de
977 spécifier le répertoire dans lequel les verrous sont
978 créés. Si <var>répertoire</var> n'est pas un
979 chemin absolu, il sera relatif au répertoire défini par la directive
980 <directive module="core">DefaultRuntimeDir</directive>.</p>
986 <name>CacheLockMaxAge</name>
987 <description>Définit la durée de vie maximale d'un verrou de cache.</description>
988 <syntax>CacheLockMaxAge <var>entier</var></syntax>
989 <default>CacheLockMaxAge 5</default>
990 <contextlist><context>server config</context><context>virtual host</context>
994 <p>La directive <directive>CacheLockMaxAge</directive> permet de
995 spécifier la durée de vie maximale d'un verrou de cache.</p>
997 <p>Un verrou plus ancien que cette valeur exprimée en secondes sera
998 ignoré, et la prochaine requête entrante sera alors en mesure de
999 recréer le verrou. Ce mécanisme permet d'éviter les mises à jour trop
1000 longues initiées par des clients lents.</p>
1003 </directivesynopsis>
1006 <name>CacheQuickHandler</name>
1007 <description>Exécute le cache à partir d'un gestionnaire rapide.</description>
1008 <syntax>CacheQuickHandler <var>on|off</var></syntax>
1009 <default>CacheQuickHandler on</default>
1010 <contextlist><context>server config</context><context>virtual host</context>
1012 <compatibility>Disponible à partir de la version 2.3.3 du serveur HTTP
1013 Apache</compatibility>
1016 <p>La directive <directive
1017 module="mod_cache">CacheQuickHandler</directive> permet de contrôler
1018 la phase au cours de laquelle la mise en cache est effectuée.</p>
1020 <p>Avec la configuration par défaut, le cache agit au cours de la
1021 phase du gestionnaire rapide. Cette phase court-circuite la majorité
1022 des traitements du serveur, et constitue le mode d'opération le plus
1023 performant pour un serveur typique. Le cache
1024 <strong>s'incruste</strong> devant le serveur, et la majorité des
1025 traitements du serveur est court-circuitée.</p>
1027 <p>Lorsque cette directive est définie à off, le cache agit comme un
1028 gestionnaire normal, et est concerné par toutes les phases de
1029 traitement d'une requête. Bien que ce mode soit moins performant que
1030 le mode par défaut, il permet d'utiliser le cache dans les cas où un
1031 traitement complet de la requête est nécessaire, comme par exemple
1032 lorsque le contenu est soumis à autorisation.</p>
1034 <highlight language="config">
1035 # Exécute le cache comme un gestionnaire normal
1036 CacheQuickHandler off
1039 <p>Lorsque le gestionnaire rapide est désactivé, l'administrateur a
1040 aussi la possibilité de choisir avec précision le point de la chaîne
1041 de filtrage où la mise en cache sera effectuée, en utilisant le
1042 filtre <strong>CACHE</strong>.</p>
1044 <highlight language="config">
1045 # Mise en cache du contenu avant l'intervention de mod_include et
1047 CacheQuickHandler off
1048 AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html
1051 <p>Si le filtre CACHE est spécifié plusieurs fois, c'est la dernière
1052 instance qui sera prise en compte.</p>
1055 </directivesynopsis>
1058 <name>CacheHeader</name>
1059 <description>Ajoute un en-tête X-Cache à la réponse.</description>
1060 <syntax>CacheHeader <var>on|off</var></syntax>
1061 <default>CacheHeader off</default>
1062 <contextlist><context>server config</context>
1063 <context>virtual host</context>
1064 <context>directory</context>
1065 <context>.htaccess</context>
1067 <compatibility>Disponible depuis la version 2.3.9 d'Apache</compatibility>
1070 <p>Lorsque la directive <directive
1071 module="mod_cache">CacheHeader</directive> est définie à on, un
1072 en-tête <strong>X-Cache</strong> est ajouté à la réponse et contient
1073 l'état du cache pour cette dernière. Si le gestionnaire normal est
1074 utilisé, cette directive peut se situer dans une section
1075 <directive type="section" module="core">Directory</directive> ou
1076 <directive type="section" module="core">Location</directive>. Si c'est
1078 gestionnaire rapide qui est utilisé, elle doit se situer dans un
1079 contexte de serveur principal ou de serveur virtuel, sinon elle sera
1083 <dt><strong>HIT</strong></dt><dd>Le contenu était à jour et a été
1084 servi depuis le cache.</dd>
1085 <dt><strong>REVALIDATE</strong></dt><dd>Le contenu était périmé, a
1086 été mis à jour, puis a été servi depuis le cache.</dd>
1087 <dt><strong>MISS</strong></dt><dd>Le contenu n'a pas été servi
1088 depuis le cache, mais directement depuis le serveur demandé.</dd>
1091 <highlight language="config">
1092 # Active l'en-tête X-Cache
1096 <highlight language="config">
1097 X-Cache: HIT from localhost
1102 </directivesynopsis>
1105 <name>CacheDetailHeader</name>
1106 <description>Ajoute un en-tête X-Cache-Detail à la réponse.</description>
1107 <syntax>CacheDetailHeader <var>on|off</var></syntax>
1108 <default>CacheDetailHeader off</default>
1109 <contextlist><context>server config</context>
1110 <context>virtual host</context>
1111 <context>directory</context>
1112 <context>.htaccess</context>
1114 <compatibility>Disponible depuis la version 2.3.9 d'Apache</compatibility>
1117 <p>Lorsque la directive <directive
1118 module="mod_cache">CacheDetailHeader</directive> est définie à on, un
1119 en-tête <strong>X-Cache-Detail</strong> est ajouté à la réponse et
1120 contient les raisons précises d'une décision d'utilisation du cache
1121 vis à vis de cette dernière.</p>
1123 <p>Ceci peut s'avérer utile au cours du développement de services
1124 RESTful mis en cache pour obtenir des informations supplémentaires à
1125 propos des décisions vis à vis du cache écrites dans les en-têtes de
1126 la réponse. Il est ainsi possible de vérifier si
1127 <code>Cache-Control</code> et d'autres en-têtes ont été correctement
1128 utilisés par le service et le client.</p>
1130 <p>Si le gestionnaire normal est utilisé, cette directive peut se
1131 situer dans une section <directive type="section"
1132 module="core">Directory</directive> ou <directive type="section"
1133 module="core">Location</directive>. Si c'est le gestionnaire
1134 rapide qui est utilisé, elle doit se situer dans un contexte de
1135 serveur principal ou de serveur virtuel, sinon elle sera ignorée.</p>
1137 <highlight language="config">
1138 # Active l'en-tête X-Cache-Detail
1139 CacheDetailHeader on
1143 X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost<br />
1147 </directivesynopsis>
1150 <name>CacheKeyBaseURL</name>
1151 <description>Remplace l'URL de base des clés du cache mandatées en
1152 inverse</description>
1153 <syntax>CacheKeyBaseURL <var>URL</var></syntax>
1154 <default>CacheKeyBaseURL http://example.com</default>
1155 <contextlist><context>server config</context>
1156 <context>virtual host</context>
1158 <compatibility>Disponible depuis la version 2.3.9 d'Apache</compatibility>
1161 <p>Lorsque la directive <directive
1162 module="mod_cache">CacheKeyBaseURL</directive> est utilisée, l'URL
1163 spécifiée sera utilisée comme URL de base pour calculer l'URL des clés
1164 du cache dans la configuration du mandataire inverse. Par défaut,
1165 c'est le protocole/nom d'hôte/port du serveur virtuel courant qui sera
1166 utilisé pour construire la clé de cache. Dans le cas d'un cluster de
1167 machines, si toutes les entrées du cache doivent posséder la même clé,
1168 cette directive permet de spécifier une nouvelle URL de base.</p>
1170 <highlight language="config">
1171 # Remplace l'URL de base de la clé de cache.
1172 CacheKeyBaseURL http://www.example.com/
1175 <note type="warning">Prenez garde en définissant cette directive. Si
1176 deux serveurs virtuels distincts possèdent accidentellement la même
1177 URL de base, les entrées en provenance d'un serveur virtuel seront
1178 servies par l'autre.</note>
1181 </directivesynopsis>
1184 <name>CacheStaleOnError</name>
1185 <description>Sert du contenu non à jour à la place de réponses 5xx.</description>
1186 <syntax>CacheStaleOnError <var>on|off</var></syntax>
1187 <default>CacheStaleOnError on</default>
1188 <contextlist><context>server config</context>
1189 <context>virtual host</context>
1190 <context>directory</context>
1191 <context>.htaccess</context>
1193 <compatibility>Disponible depuis la version 2.3.9 d'Apache</compatibility>
1196 <p>Lorsque la directive <directive
1197 module="mod_cache">CacheStaleOnError</directive> est définie à on, et
1198 si des données non mises à jour sont disponibles dans le cache, ce
1199 dernier renverra ces données, plutôt qu'une éventuelle réponse 5xx en
1200 provenance du serveur d'arrière-plan. Alors que l'en-tête
1201 Cache-Control envoyé par les clients sera respecté, et que les clients
1202 recevront donc dans ce cas la réponse 5xx brute à leur requête, cette
1203 réponse 5xx renvoyée au client n'invalidera pas le contenu dans le
1206 <highlight language="config">
1207 # Sert des données non mises à jour en cas d'erreur.
1208 CacheStaleOnError on
1212 </directivesynopsis>
projects / apache / blob