| <?xml version="1.0" encoding="UTF-8" ?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?> |
| <!-- English Revision: 1873722 --> |
| <!-- French translation : Lucien GENTIS --> |
| <!-- Reviewed by : Vincent Deffontaines --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_deflate.xml.meta"> |
| |
| <name>mod_deflate</name> |
| <description>Comprime le contenu avant de le servir au |
| client</description> |
| <status>Extension</status> |
| <sourcefile>mod_deflate.c</sourcefile> |
| <identifier>deflate_module</identifier> |
| |
| <summary> |
| <p>Le module <module>mod_deflate</module> implémente le filtre de |
| sortie <code>DEFLATE</code> qui permet de comprimer la sortie de |
| votre serveur avant de l'envoyer au client sur le réseau.</p> |
| </summary> |
| <seealso><a href="../filter.html">Les filtres</a></seealso> |
| |
| <section id="supportedencodings"><title>Codages supportés</title> |
| <p>Le seul codage supporté est <code>gzip</code> afin d'assurer une complète |
| compatibilité avec les anciens navigateurs. Le codage <code>deflate</code> |
| n'est donc pas supporté ; voir à ce sujet la <a |
| href="https://zlib.net/zlib_faq.html#faq39">documentation de zlib</a> pour une |
| explication détaillée. |
| </p> |
| </section> |
| |
| <section id="recommended"><title>Exemples de configurations</title> |
| <note type="warning"><title>Compression et TLS</title> |
| <p>Certaines applications web sont vulnérables à une attaque pour |
| vol d'informations lorsqu'une connexion TLS transporte des |
| données compressées par deflate. Pour plus de détails, |
| documentez-vous sur la famille d'attaques "BREACH".</p> |
| </note> |
| <p>Voici un exemple simple de configuration qui permet de comprimer |
| les types de contenu à base de texte.</p> |
| |
| <example><title>Ne comprime que certains types de documents</title> |
| <highlight language="config"> |
| AddOutputFilterByType DEFLATE text/html text/plain text/xml text/css text/javascript application/javascript |
| </highlight> |
| </example> |
| |
| </section> |
| |
| <section id="enable"><title>Activation de la compression</title> |
| <note type="warning"><title>Compression et TLS</title> |
| <p>Certaines applications web sont vulnérables à une attaque pour |
| vol d'informations lorsqu'une connexion TLS transporte des |
| données compressées par deflate. Pour plus de détails, |
| documentez-vous sur la famille d'attaques "BREACH".</p> |
| </note> |
| |
| <section id="output"><title>Compression de la sortie</title> |
| <p>La compression est implémentée par le <a |
| href="../filter.html">filtre</a> <code>DEFLATE</code>. La |
| directive suivante active la compression des documents dans le |
| conteneur où elle est placée :</p> |
| |
| <highlight language="config"> |
| SetOutputFilter DEFLATE |
| SetEnvIfNoCase Request_URI "\.(?:gif|jpe?g|png)$" no-gzip |
| </highlight> |
| |
| <p>Si vous voulez limiter la compression à certains types MIME |
| particuliers, vous pouvez utiliser la directive <directive |
| module="mod_filter">AddOutputFilterByType</directive>. Voici un exemple |
| où la compression n'est activée que pour les fichiers html de la |
| documentation d'Apache :</p> |
| |
| <highlight language="config"> |
| <Directory "/your-server-root/manual"> |
| AddOutputFilterByType DEFLATE text/html |
| </Directory> |
| </highlight> |
| |
| <note><title>Note</title> |
| Le filtre <code>DEFLATE</code> est toujours inséré après les |
| filtres RESOURCE comme PHP ou SSI. Il n'affecte jamais les |
| sous-requêtes internes. |
| </note> |
| <note><title>Note</title> |
| La variable d'environnement <code>force-gzip</code>, définie à |
| l'aide de la directive <directive |
| module="mod_env">SetEnv</directive>, permet d'ignorer la |
| configuration de votre navigateur quant aux codages acceptés, et |
| d'envoyer sans condition une sortie comprimée. |
| </note> |
| |
| </section> |
| <section id="inflate"><title>Décompression de la sortie</title> |
| <p>Le module <module>mod_deflate</module> fournit aussi un filtre |
| permettant de décomprimer un corps de réponse comprimé par gzip. |
| Pour activer cette fonctionnalité, vous devez insérer le filtre |
| <code>INFLATE</code> dans la chaîne de filtrage en sortie via la |
| directive <directive module="core">SetOutputFilter</directive> ou |
| <directive module="mod_mime">AddOutputFilter</directive>, comme |
| dans l'exemple suivant :</p> |
| |
| <highlight language="config"> |
| <Location "/dav-area"> |
| ProxyPass "http://example.com/" |
| SetOutputFilter INFLATE |
| </Location> |
| </highlight> |
| |
| <p>Dans cet exemple, les sorties comprimées par gzip en |
| provenance de example.com seront décomprimées afin de pouvoir |
| être éventuellement traitées par d'autres filtres. |
| </p> |
| |
| </section> |
| <section id="input"><title>Décompression de l'entrée</title> |
| <p>Le module <module>mod_deflate</module> fournit également un filtre |
| permettant de décomprimer un corps de requête comprimé par gzip. |
| Pour activer cette fonctionnalité, vous devez insérer le filtre |
| <code>DEFLATE</code> dans la chaîne de filtrage en entrée via la |
| directive <directive module="core">SetInputFilter</directive> ou |
| <directive module="mod_mime">AddInputFilter</directive>, comme |
| dans l'exemple suivant :</p> |
| |
| <highlight language="config"> |
| <Location "/dav-area"> |
| SetInputFilter DEFLATE |
| </Location> |
| </highlight> |
| |
| <p>Désormais, si une requête contient un en-tête |
| <code>Content-Encoding: gzip</code>, son corps sera |
| automatiquement décomprimé. Peu de navigateurs sont actuellement |
| en mesure de comprimer les corps de requêtes. Cependant, |
| certaines applications spécialisées supportent les requêtes |
| comprimées, comme par exemple certains clients <a |
| href="http://www.webdav.org">WebDAV</a>.</p> |
| |
| <note type="warning"><title>Note à propos de l'en-tête |
| <code>Content-Length</code></title> |
| <p>Si vous évaluez vous-même la taille du corps de requête, |
| <em>ne faites pas confiance à l'en-tête |
| <code>Content-Length</code>!</em> L'en-tête |
| Content-Length indique la longueur des données en provenance du |
| client, et <em>non</em> la quantité d'octets que représente le |
| flux de données décompressé.</p> |
| </note> |
| </section> |
| </section> |
| |
| <section id="proxies"><title>Prise en compte des serveurs mandataires</title> |
| |
| <p>Le module <module>mod_deflate</module> envoie un en-tête de |
| réponse HTTP <code>Vary: Accept-Encoding</code> pour avertir les |
| mandataires qu'une réponse enregistrée dans le cache ne doit être |
| envoyée qu'aux clients qui ont envoyé l'en-tête de requête |
| <code>Accept-Encoding</code> approprié. Ceci permet d'éviter l'envoi |
| d'un contenu comprimé à un client qui ne sera pas en mesure |
| de l'interpréter.</p> |
| |
| <p>Si vous avez défini des exclusions spécifiques dépendant, par |
| exemple, de l'en-tête <code>User-Agent</code>, vous devez |
| ajouter manuellement des données à l'en-tête <code>Vary</code> afin |
| d'informer les mandataires des restrictions supplémentaires. Par |
| exemple, dans la configuration classique où l'addition du filtre |
| <code>DEFLATE</code> dépend du contenu de l'en-tête |
| <code>User-Agent</code>, vous devez spécifier :</p> |
| |
| <highlight language="config"> |
| Header append Vary User-Agent |
| </highlight> |
| |
| <p>Si votre décision de comprimer le contenu dépend d'autres |
| informations que celles contenues dans les en-têtes de la requête |
| (par exemple la version HTTP), vous devez attribuer à l'en-tête |
| <code>Vary</code> la valeur <code>*</code>, ce qui permet d'empêcher |
| les mandataires compatibles de tout mettre en cache.</p> |
| |
| <example><title>Exemple</title> |
| <highlight language="config"> |
| Header set Vary * |
| </highlight> |
| </example> |
| </section> |
| |
| <section id="precompressed"><title>Servir du contenu précompressé</title> |
| |
| <p>Comme <module>mod_deflate</module> recompresse le contenu demandé à |
| chaque requête, il est possible de gagner en performances en précompressant |
| ce contenu, et en forçant <module>mod_deflate</module> à servir ce contenu |
| précompressé sans avoir à le recompresser à chaque requête. Pour ce faire, |
| utilisez une configuration du style :</p> |
| |
| <highlight language="config"> |
| <IfModule mod_headers.c> |
| # Servir des fichiers JS et CSS compressés avec gzip, s'ils existent, et |
| # si le client accepte gzip. |
| RewriteCond "%{HTTP:Accept-encoding}" "gzip" |
| RewriteCond "%{REQUEST_FILENAME}\.gz" -s |
| RewriteRule "^(.*)\.(css|js)" "$1\.$2\.gz" [QSA] |
| |
| # Servir des types de contenus corrects, et empêcher mod_deflate |
| # d'effectuer un double gzip. |
| RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-gzip:1] |
| RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-gzip:1] |
| |
| |
| <FilesMatch "(\.js\.gz|\.css\.gz)$"> |
| # Servir le type de codage correct. |
| Header append Content-Encoding gzip |
| |
| # Force les mandataires à mettre en cache séparément les fichiers |
| # css/js gzippés & non gzippés. |
| Header append Vary Accept-Encoding |
| </FilesMatch> |
| </IfModule> |
| </highlight> |
| |
| </section> |
| |
| <directivesynopsis> |
| <name>DeflateFilterNote</name> |
| <description>Enregistre le taux de compression sous la forme d'une note |
| à des fins de journalisation</description> |
| <syntax>DeflateFilterNote [<var>type</var>] <var>nom de la note</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>La directive <directive>DeflateFilterNote</directive> permet de |
| spécifier qu'une note à propos du taux de compression doit être |
| attachée à la requête. Le nom de la note est passé sous la forme |
| d'un argument de la directive. Vous pouvez utiliser cette note à des |
| fins statistiques en enregistrant sa valeur dans votre <a |
| href="../logs.html#accesslog">journal des accès</a>.</p> |
| |
| <example><title>Exemple</title> |
| <highlight language="config"> |
| DeflateFilterNote ratio |
| |
| LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' deflate |
| CustomLog "logs/deflate_log" deflate |
| </highlight> |
| </example> |
| |
| <p>Pour extraire des informations plus précises de vos journaux, |
| vous pouvez utiliser l'argument <var>type</var> pour spécifier le |
| type de données de la note enregistrée dans le journal. |
| <var>type</var> peut prendre une des valeurs suivantes :</p> |
| |
| <dl> |
| <dt><code>Input</code></dt> |
| <dd>Enregistre dans la note la taille en octets du flux en entrée |
| du filtre.</dd> |
| |
| <dt><code>Output</code></dt> |
| <dd>Enregistre dans la note la taille en octets du flux en sortie |
| du filtre.</dd> |
| |
| <dt><code>Ratio</code></dt> |
| <dd>Enregistre le taux de compression (<code>sortie/entrée * |
| 100</code>) dans la note. Il s'agit de la valeur par défaut si |
| l'argument <var>type</var> est omis.</dd> |
| </dl> |
| |
| <p>Vous pouvez donc configurer votre journalisation de la manière |
| suivante :</p> |
| |
| <example><title>Journalisation détaillée</title> |
| <highlight language="config"> |
| DeflateFilterNote Input instream |
| DeflateFilterNote Output outstream |
| DeflateFilterNote Ratio ratio |
| |
| LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' deflate |
| CustomLog "logs/deflate_log" deflate |
| </highlight> |
| </example> |
| </usage> |
| <seealso><module>mod_log_config</module></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateBufferSize</name> |
| <description>Taille du fragment que zlib devra comprimer en une seule |
| fois</description> |
| <syntax>DeflateBufferSize <var>valeur</var></syntax> |
| <default>DeflateBufferSize 8096</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>La directive <directive>DeflateBufferSize</directive> permet de |
| spécifier la taille en octets du fragment que zlib devra comprimer |
| en une seule fois. Si la taille de la réponse compressée est supérieure à |
| celle spécifiée par cette directive, httpd passera à un mode d'encodage |
| fragmenté (l'en-tête HTTP <code>Transfer-Encoding</code> prend la valeur |
| <code>Chunked</code>), ceci ayant comme effet de bord de ne définir aucun |
| en-tête HTTP <code>Content-Length</code>. Il est important de connaître ce |
| comportement, particulièrement lorsque httpd travaille derrière des |
| mandataires inverses avec mise en cache, ou lorsque httpd est configuré pour |
| utiliser <module>mod_cache</module> et <module>mod_cache_disk</module> car |
| les réponses HTTP sans en-tête <code>Content-Length</code> peuvent ne pas |
| être mises en cache.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateWindowSize</name> |
| <description>Taille de la fenêtre de compression zlib</description> |
| <syntax>DeflateWindowSize <var>valeur</var></syntax> |
| <default>DeflateWindowSize 15</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>La directive <directive>DeflateWindowSize</directive> permet de |
| spécifier la fenêtre de compression zlib (une valeur comprise entre |
| 1 et 15). En général, plus grande sera la taille de la fenêtre, plus |
| grand sera le taux de compression auquel on pourra s'attendre.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| |
| <name>DeflateMemLevel</name> |
| <description>La quantité de mémoire utilisable par zlib pour la |
| compression</description> |
| <syntax>DeflateMemLevel <var>valeur</var></syntax> |
| <default>DeflateMemLevel 9</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>La directive <directive>DeflateMemLevel</directive> permet de |
| spécifier la quantité de mémoire utilisable par zlib pour la |
| compression (une valeur comprise entre 1 et 9).</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateCompressionLevel</name> |
| <description>Le niveau de compression que nous appliquons à la |
| sortie</description> |
| <syntax>DeflateCompressionLevel <var>valeur</var></syntax> |
| <default>La valeur par défaut de zlib</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>La directive <directive>DeflateCompressionLevel</directive> |
| permet de spécifier le niveau de compression à utiliser ; plus |
| grande est la valeur, meilleure sera la compression, mais plus grand |
| sera aussi le temps CPU nécessaire pour effectuer le |
| traitement.</p> |
| <p>La valeur doit être comprise entre 1 (compression minimale) et 9 |
| (compression maximale).</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateInflateLimitRequestBody</name> |
| <description>Taille maximale des corps de requête décompressés</description> |
| <syntax>DeflateInflateLimitRequestBody <var>value</var></syntax> |
| <default>Aucune limite, mais LimitRequestBody s'applique après la |
| compression</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| <compatibility>Disponible à partir de la version 2.4.10 du serveur HTTP |
| Apache</compatibility> |
| |
| <usage> |
| <p>La directive |
| <directive>DeflateInflateLimitRequestBody</directive> permet de |
| spécifier la taille maximale d'un corps de requête décompressé. Si |
| elle n'est pas définie, c'est la valeur de la directive <directive |
| module="core">LimitRequestBody</directive> qui s'applique au corps |
| de requête décompressé.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateInflateRatioLimit</name> |
| <description>Ratio de décompression maximum pour les corps de requêtes</description> |
| <syntax>DeflateInflateRatioLimit <var>value</var></syntax> |
| <default>DeflateInflateRatioLimit 200</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| <compatibility>Disponible à partir de la version 2.4.10 du serveur HTTP |
| Apache</compatibility> |
| |
| <usage> |
| <p>La directive <directive>DeflateInflateRatioLimit</directive> permet de |
| définir le ratio maximum entre la taille d'un corps de requête compressé et |
| sa taille décompressée. Ce ratio est vérifié au fur et à mesure de l'arrivée |
| du corps de requête, et s'il est dépassé plus de <directive |
| module="mod_deflate">DeflateInflateRatioBurst</directive> fois, le |
| traitement de la requête est interrompu.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateInflateRatioBurst</name> |
| <description>Nombre maximal de fois que le ratio de décompression d'un |
| corps de requête peut être dépassé</description> |
| <syntax>DeflateInflateRatioBurst <var>value</var></syntax> |
| <default>DeflateInflateRatioBurst 3</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| <context>directory</context><context>.htaccess</context></contextlist> |
| <override>All</override> |
| <compatibility>Disponible à partir de la version 2.4.10 du serveur HTTP |
| Apache</compatibility> |
| |
| <usage> |
| <p>La directive <directive>DeflateInflateRatioBurst</directive> permet de |
| spécifier le nombre maximal de fois que la valeur de la directive <directive |
| module="mod_deflate">DeflateInflateRatioLimit</directive> peut être dépassé |
| avant l'arrêt du traitement de la requête.</p> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>DeflateAlterETag</name> |
| <description>Comment l'en-tête sortant ETag doit être modifié au cours |
| de la compression</description> |
| <syntax>DeflateAlterETag AddSuffix|NoChange|Remove</syntax> |
| <default>DeflateAlterETag AddSuffix</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>La directive <directive>DeflateAlterETag</directive> permet de |
| spécifier comment l'en-tête ETag doit être modifié lorsqu'une |
| réponse est compressée.</p> |
| <dl> |
| <dt>AddSuffix</dt> |
| <dd><p>Ajoute la méthode de compression à la fin de l'en-tête, ce |
| qui a pour effet d'attribuer un en-tête ETag unique aux |
| représentations compressées et non compressées. C'est l'option par |
| défaut depuis la version 2.4.0, mais empêche de servir des |
| codes d'état "HTTP Not Modified" (304) en réponse aux requêtes pour un |
| contenu compressé.</p></dd> |
| <dt>NoChange</dt> |
| <dd><p>Ne modifie pas l'en-tête ETag dans une réponse compressée. |
| C'était l'option par |
| défaut avant la version 2.4.0, mais cela ne respectait pas la |
| préconisation HTTP/1.1 selon laquelle chaque représentation de la |
| même ressource doit posséder un en-tête ETag unique.</p></dd> |
| <dt>Remove</dt> |
| <dd><p>Supprime l'en-tête ETag dans les réponses compressées, ce qui |
| a pour effet de rendre impossibles certaines requêtes |
| conditionnelles, mais permet d'éviter les inconvénients des options |
| précédentes.</p></dd> |
| </dl> |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |
| |