Serveur HTTP Apache Version 2.4

Apache > Serveur HTTP > Documentation > Version 2.4 > Modules

# Module Apache mod_brotli

Description: | Compression du contenu via Brotli avant sa livraison au client
Statut: | Extension
Identificateur de Module: | brotli_module
Fichier Source: | mod_brotli.c
Compatibilité: | Disponible à partir de la version 2.4.26 du serveur HTTP Apache

### Sommaire

Le module `mod_brotli` fournit le filtre en sortie `BROTLI_COMPRESS` qui permet de compresser un contenu avant sa livraison au client en utilisant la bibliothèque brotli. Ce filtre est implémenté en utilisant la bibliothèque Brotli que l'on peut trouver à https://github.com/google/brotli.

### Sujets

- Exemples de configurations
- Activation de la compression
- Interaction avec les serveurs mandataires
- Servir un contenu pré-compressé

### Directives

### Traitement des bugs

- Journal des modifications de httpd
- Problèmes connus
- Signaler un bug

### Voir aussi

- Filters

## Exemples de configurations

### Compression et TLS

Certaines applications web sont vulnérables à une attaque de type vol d'informations lorsqu'une connexion TLS transmet des données compressées. Pour plus d'informations, étudiez en détail la famille d'attaques "BREACH".

Voici une configuration simple qui compresse des types de contenus courants au format texte :

### Compression de certains types seulement

    AddOutputFilterByType BROTLI_COMPRESS text/html text/plain text/xml text/css text/javascript application/javascript

## Activation de la compression

### Compression et TLS

Certaines applications web sont vulnérables à une attaque de type vol d'informations lorsqu'une connexion TLS transmet des données compressées. Pour plus d'informations, étudiez en détail la famille d'attaques "BREACH".

### Compression en sortie

La compression est implémentée par le filtre `BROTLI_COMPRESS`. La directive suivante active la compression pour les documents correspondant au conteneur dans lequel elle est placée :

    SetOutputFilter BROTLI_COMPRESS
    SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-brotli

Si vous voulez restreindre la compression à certains types MIME particuliers, vous pouvez utiliser la directive `AddOutputFilterByType`. Dans l'exemple suivant, l'activation de la compression est restreinte aux fichiers html de la documentation d'Apache :

    <Directory "/your-server-root/manual">
        AddOutputFilterByType BROTLI_COMPRESS text/html
    </Directory>

### Note

Le filtre `BROTLI_COMPRESS` est toujours inséré après les filtres RESOURCE comme PHP ou SSI. Il n'affecte jamais les sous-requêtes internes.

### Note

Définie via `SetEnv`, la variable d'environnement `no-brotli` permet de désactiver la compression brotli pour une requête particulière, et ceci même si elle est supportée par le client.

## Interaction avec les serveurs mandataires

Le module `mod_brotli` envoie un en-tête de réponse HTTP `Vary:Accept-Encoding` pour indiquer aux mandataires qu'une réponse mise en cache ne doit être envoyée qu'aux clients qui envoient l'en-tête de requête `Accept-Encoding` approprié. Ceci permet d'éviter d'envoyer du contenu compressé à un client qui ne sera pas en mesure de le décompresser.

Si vous utilisez des exclusions spéciales dépendant, par exemple, de l'en-tête `User-Agent`, vous devez faire un ajout manuel à l'en-tête `Vary` afin d'informer les mandataires des restrictions supplémentaires. Par exemple, dans une configuration typique où l'addition du filtre `BROTLI_COMPRESS` dépend de l'en-tête `User-Agent`, vous devez ajouter :

    Header append Vary User-Agent

Si votre décision d'utiliser la compression ou non dépend d'autres informations que le contenu d'en-têtes de requêtes (par exemple la version HTTP), vous devez affecter la valeur `*` à l'en-tête `Vary`. Ceci permet d'éviter que des mandataires qui le supportent n'effectuent une mise en cache intégrale.

### Exemple

    Header set Vary *

## Servir un contenu pré-compressé

comme `mod_brotli` compresse systématiquement un contenu pour chaque requête le concernant, il est possible d'obtenir un gain en performance en pré-compressant le contenu et en disant à mod_brotli de le servir sans le recompresser. Pour cela, vous pouvez utiliser une configuration du style :

    <IfModule mod_headers.c>
        # Sert des fichiers CSS compressés par brotli, s'ils existent
        # et si le client supporte brotli.
        RewriteEngine On
        RewriteCond "%{HTTP:Accept-encoding}" "br"
        RewriteCond "%{LA-U:REQUEST_FILENAME}.br" "-s"
        RewriteRule "^(.*)\.css"              "$1.css.br" [QSA]

        # Sert des fichiers JS compressés par brotli, s'ils existent
        # et si le client supporte brotli.
        RewriteCond "%{HTTP:Accept-encoding}" "br"
        RewriteCond "%{LA-U:REQUEST_FILENAME}.br" "-s"
        RewriteRule "^(.*)\.js"               "$1.js.br" [QSA]

        # Sert des types de contenu corrects, et évite la double compression.
        RewriteRule "\.css\.br$" "-" [T=text/css,E=no-brotli:1,E=no-gzip:1]
        RewriteRule "\.js\.br$"  "-" [T=text/javascript,E=no-brotli:1,E=no-gzip:1]

        <FilesMatch "(\.js\.br|\.css\.br)$">
          # Sert un type d'encodage correct.
          Header append Content-Encoding br

          # Force les mandataires à mettre en cache séparément les fichiers css/js
          # compressés ou non par brotli.
          Header append Vary Accept-Encoding
        </FilesMatch>
    </IfModule>

## Directive BrotliAlterETag

Description: | Comment l'en-tête de réponse ETag doit être modifié au cours de la compression
Syntaxe: | `BrotliAlterETag AddSuffix|NoChange|Remove`
Défaut: | `BrotliAlterETag AddSuffix`
Contexte: | configuration globale, serveur virtuel
Statut: | Extension
Module: | mod_brotli

La directive `BrotliAlterETag` permet d'indiquer comment l'en-tête ETag doit être modifié lorsqu'une réponse est compressée.

AddSuffix

  Ajoute la méthode de compression à la fin de l'en-tête ETag, ce qui implique que les représentations compressées et non compressées possèderont des en-têtes ETag uniques. C'est le comportement par défaut depuis la version 2.4.0 avec un autre module de compression dynamique, mod-deflate. Ce paramètre permet d'éviter l'envoi de messages "HTTP Not Modified" (304) en réponse aux requêtes conditionnelles pour des contenus compressés.

NoChange

  Ne modifie pas l'en-tête ETag d'une réponse compressée. C'était le comportement par défaut avant la version 2.4.0 avec un autre module de compression dynamique, mod-deflate. Ce paramètre ne respecte pas la propriété HTTP/1.1 selon laquelle toutes les représentations d'une même ressource ont des en-têtes ETag uniques.

Remove

  Supprime l'en-tête ETag des réponses compressées, ce qui rend impossibles certaines requêtes conditionnelles, mais évite les inconvénients des options précédentes.

## Directive BrotliCompressionMaxInputBlock

Description: | Taille maximale du bloc de données en entrée
Syntaxe: | `BrotliCompressionMaxInputBlock value`
Défaut: | `(automatic)`
Contexte: | configuration globale, serveur virtuel
Statut: | Extension
Module: | mod_brotli

La directive `BrotliCompressionMaxInputBlock` permet de spécifier la taille maximale du bloc de données en entrée entre 16 et 24, sachant que plus cette taille sera grande, plus grande sera la quantité de mémoire consommée.

## Directive BrotliCompressionQuality

Description: | Qualité de la compression
Syntaxe: | `BrotliCompressionQuality value`
Défaut: | `BrotliCompressionQuality 5`
Contexte: | configuration globale, serveur virtuel
Statut: | Extension
Module: | mod_brotli

La directive `BrotliCompressionQuality` permet de spécifier la qualité de la compression (une valeur entre 0 et 11). Les valeurs les plus hautes correspondent à une compression de meilleure qualité mais plus lente.

## Directive BrotliCompressionWindow

Description: | Taille de la fenêtre de compression glissante brotli
Syntaxe: | `BrotliCompressionWindow value`
Défaut: | `BrotliCompressionWindow 18`
Contexte: | configuration globale, serveur virtuel
Statut: | Extension
Module: | mod_brotli

La directive `BrotliCompressionWindow` permet de spécifier la taille de la fenêtre de compression glissante brotli (une valeur comprise entre 10 et 24). Une taille de fenêtre plus grande peut améliorer la qualité de la compression mais consomme d'avantage de mémoire.

## Directive BrotliFilterNote

Description: | Enregistre le taux de compression dans une note à des fins de journalisation
Syntaxe: | `BrotliFilterNote [type] notename`
Contexte: | configuration globale, serveur virtuel
Statut: | Extension
Module: | mod_brotli

La directive `BrotliFilterNote` permet d'indiquer qu'une note à propos du taux de compression doit être attachée à la requête. L'argument notename permet de spécifier le nom de la note. Vous pouvez utiliser cette note à des fins de statistiques en ajoutant l'information correspondante à votre access log.

### Exemple

    BrotliFilterNote ratio

    LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' brotli
    CustomLog "logs/brotli_log" brotli

Si vous souhaitez que l'information enregistrée dans vos journaux soit plus pertinente, vous pouvez renseigner l'argument optionnel type afin de spécifier le type de données à enregistrer dans la note à journaliser. L'argument type accepte les valeurs suivantes :

`Input`
  Enregistre dans la note le nombre d'octets contenus dans le flux d'entrée du filtre.
`Output`
  Enregistre dans la note le nombre d'octets contenus dans le flux de sortie du filtre.
`Ratio`
  Enregistre dans la note le taux de compression (`output/input * 100`). Il s'agit de l'option par défaut si l'argument type est omis.

Vous pouvez alors configurer vos journaux de la manière suivante :

### Journalisation spécifique

    BrotliFilterNote Input instream
    BrotliFilterNote Output outstream
    BrotliFilterNote Ratio ratio

    LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' brotli
    CustomLog "logs/brotli_log" brotli

### Voir aussi

- `mod_log_config`