diff options
| author | Vincent Deffontaines <gryzor@apache.org> | 2017-12-18 19:20:38 +0100 |
|---|---|---|
| committer | Vincent Deffontaines <gryzor@apache.org> | 2017-12-18 19:20:38 +0100 |
| commit | 7b38f9a12c74c3c84a30f0fd9409d3adb1c05234 (patch) | |
| tree | fbbf3d7888cb20008608e33b54f35a4f1d1c55a1 /docs/manual/mod | |
| parent | Fixed encoding in two previous commits (diff) | |
| download | apache2-7b38f9a12c74c3c84a30f0fd9409d3adb1c05234.tar.xz apache2-7b38f9a12c74c3c84a30f0fd9409d3adb1c05234.zip | |
New .fr translations
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1818602 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to '')
| -rw-r--r-- | docs/manual/mod/mod_authnz_fcgi.xml.fr | 560 | ||||
| -rw-r--r-- | docs/manual/mod/mod_authnz_fcgi.xml.meta | 1 | ||||
| -rw-r--r-- | docs/manual/mod/mod_brotli.xml.fr | 321 | ||||
| -rw-r--r-- | docs/manual/mod/mod_brotli.xml.meta | 1 |
4 files changed, 883 insertions, 0 deletions
diff --git a/docs/manual/mod/mod_authnz_fcgi.xml.fr b/docs/manual/mod/mod_authnz_fcgi.xml.fr new file mode 100644 index 0000000000..ed264c0c84 --- /dev/null +++ b/docs/manual/mod/mod_authnz_fcgi.xml.fr @@ -0,0 +1,560 @@ +<?xml version="1.0" encoding="ISO-8859-1" ?> +<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?> +<!-- English Revision : 1793934 --> +<!-- 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_authnz_fcgi.xml.meta"> + +<name>mod_authnz_fcgi</name> +<description>Permet à une application d'autorisation FastCGI de gérer +l'authentification et l'autorisation httpd.</description> +<status>Extension</status> +<sourcefile>mod_authnz_fcgi.c</sourcefile> +<identifier>authnz_fcgi_module</identifier> +<compatibility>Disponible à partir de la version 2.4.10 du serveur HTTP +Apache</compatibility> + +<summary> + <p>Ce module permet aux applications d'autorisation FastCGI + d'authentifier les utilisateurs et de contrôler leur accès aux + ressources. Il supporte les systèmes d'autorisation FastCGI + génériques qui participent en une seule phase à l'authentification + et à l'autorisation, ainsi que les processus d'authentification et + d'autorisation spécifiques à Apache httpd qui interviennent en une + ou plusieurs phases.</p> + + <p>Les processus d'autorisation FastCGI peuvent authentifier un + utilisateur via son identificateur et son mot de passe comme dans le + processus d'authentification basique, ou via un mécanisme + arbitraire.</p> +</summary> + +<seealso><a href="../howto/auth.html">Authentification, autorisation et +contrôle d'accès</a></seealso> +<seealso><module>mod_auth_basic</module></seealso> +<seealso><program>fcgistarter</program></seealso> +<seealso><module>mod_proxy_fcgi</module></seealso> + +<section id="invocations"><title>Modes d'invocation</title> + + <p>Les modes d'invocation des processus d'autorisation FastCGI que + ce module supporte se distinguent par deux caractéristiques : le + <em>type</em> et le <em>mécanisme</em> d'authentification.</p> + + <p>Le <em>Type</em> est simplement <code>authn</code> pour + l'authentification, <code>authz</code> pour l'autorisation et + <code>authnz</code> l'authentification et l'autorisation.</p> + + <p>Le <em>mécanisme</em> d'authentification fait référence aux + mécanismes d'authentification et aux phases de traitement de la + configuration de Apache httpd, et peut être + <code>AuthBasicProvider</code>, <code>Require</code>, ou + <code>check_user_id</code>. Les deux premiers mécanismes + correspondent aux directives utilisées pour participer aux phases de + traitement appropriées.</p> + + <p>Description de chaque mode:</p> + + <dl> + <dt><em>Type</em> <code>authn</code>, <em>mechanism</em> + <code>AuthBasicProvider</code></dt> + + <dd>Dans ce mode, la variable <code>FCGI_ROLE</code> est définie à + <code>AUTHORIZER</code>, et la variable + <code>FCGI_APACHE_ROLE</code> à <code>AUTHENTICATOR</code>. + L'application doit être spécifiée en tant que fournisseur de type + <em>authn</em> via la directive <directive + module="mod_authnz_fcgi">AuthnzFcgiDefineProvider</directive>, et + activée via la directive <directive + module="mod_auth_basic">AuthBasicProvider</directive>. Lorsqu'elle + est invoquée, l'application est censée authentifier le client à + l'aide de l'identifiant et du mot de passe de l'utilisateur. + Exemple d'application : + +<highlight language="perl"> +#!/usr/bin/perl +use FCGI; +my $request = FCGI::Request(); +while ($request->Accept() >= 0) { + die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR"; + die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER"; + die if !$ENV{'REMOTE_PASSWD'}; + die if !$ENV{'REMOTE_USER'}; + + print STDERR "This text is written to the web server error log.\n"; + + if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") && + $ENV{'REMOTE_PASSWD'} eq "bar" ) { + print "Status: 200\n"; + print "Variable-AUTHN_1: authn_01\n"; + print "Variable-AUTHN_2: authn_02\n"; + print "\n"; + } + else { + print "Status: 401\n\n"; + } +} +</highlight> + + Exemple de configuration httpd : +<highlight language="config"> +AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/ +<Location "/protected/"> + AuthType Basic + AuthName "Restricted" + AuthBasicProvider FooAuthn + Require ... +</Location> +</highlight> + </dd> + + <dt><em>Type</em> <code>authz</code>, <em>mechanism</em> + <code>Require</code></dt> + <dd>Dans ce mode, la variable <code>FCGI_ROLE</code> est définie à + <code>AUTHORIZER</code> et <code>FCGI_APACHE_ROLE</code> à + <code>AUTHORIZER</code>. L'application doit être spécifiée en tant + que fournisseur de type <em>authz</em> via la directive <directive + module="mod_authnz_fcgi">AuthnzFcgiDefineProvider</directive>. + Lorsqu'elle est invoquée, l'application est censée contrôler les + accès du client à l'aide de l'identifiant utilisateur et d'autres + données contenues dans la requête. Exemple d'application : +<highlight language="perl"> +#!/usr/bin/perl +use FCGI; +my $request = FCGI::Request(); +while ($request->Accept() >= 0) { + die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHORIZER"; + die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER"; + die if $ENV{'REMOTE_PASSWD'}; + + print STDERR "This text is written to the web server error log.\n"; + + if ($ENV{'REMOTE_USER'} eq "foo1") { + print "Status: 200\n"; + print "Variable-AUTHZ_1: authz_01\n"; + print "Variable-AUTHZ_2: authz_02\n"; + print "\n"; + } + else { + print "Status: 403\n\n"; + } +} +</highlight> + + Exemple de configuration httpd : +<highlight language="config"> +AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10103/ +<Location "/protected/"> + AuthType ... + AuthName ... + AuthBasicProvider ... + Require FooAuthz +</Location> +</highlight> + </dd> + + <dt><em>Type</em> <code>authnz</code>, <em>mechanism</em> + <code>AuthBasicProvider</code> <em>+</em> <code>Require</code></dt> + + <dd>Dans ce mode qui supporte le protocole d'autorisation web + server-agnostic FastCGI, la variable <code>FCGI_ROLE</code> est + définie à <code>AUTHORIZER</code> et <code>FCGI_APACHE_ROLE</code> + n'est pas définie. L'application doit être spécifiée en tant que + fournisseur de type <em>authnz</em> via la directive <directive + module="mod_authnz_fcgi">AuthnzFcgiDefineProvider</directive>. + L'application est censée assurer l'authentification et + l'autorisation au cours d'une même invocation à l'aide de + l'identifiant et du mot de passe de l'utilisateur et d'autres + données contenues dans la requête. L'invocation de l'application + intervient au cours de la phase d'authentification de l'API Apache + httpd. Si l'application renvoie le code 200, et si le même + fournisseur est invoqué au cours de la phase d'autorisation (via + une directive <directive>Require</directive>), mod_authnz_fcgi + renverra un code de type success pour la phase d'autorisation sans + invoquer l'application. Exemple d'application : +<highlight language="perl"> +#!/usr/bin/perl +use FCGI; +my $request = FCGI::Request(); +while ($request->Accept() >= 0) { + die if $ENV{'FCGI_APACHE_ROLE'}; + die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER"; + die if !$ENV{'REMOTE_PASSWD'}; + die if !$ENV{'REMOTE_USER'}; + + print STDERR "This text is written to the web server error log.\n"; + + if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") && + $ENV{'REMOTE_PASSWD'} eq "bar" && + $ENV{'REQUEST_URI'} =~ m%/bar/.*%) { + print "Status: 200\n"; + print "Variable-AUTHNZ_1: authnz_01\n"; + print "Variable-AUTHNZ_2: authnz_02\n"; + print "\n"; + } + else { + print "Status: 401\n\n"; + } +} +</highlight> + + Exemple de configuration httpd : +<highlight language="config"> +AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/ +<Location "/protected/"> + AuthType Basic + AuthName "Restricted" + AuthBasicProvider FooAuthnz + Require FooAuthnz +</Location> +</highlight> + </dd> + + <dt><em>Type</em> <code>authn</code>, <em>mechanism</em> + <code>check_user_id</code></dt> + + <dd>Dans ce mode, la variable <code>FCGI_ROLE</code> est définie à + <code>AUTHORIZER</code> et <code>FCGI_APACHE_ROLE</code> à + <code>AUTHENTICATOR</code>. L'application doit être spécifiée en + tant que fournisseur de type <em>authn</em> via une directive + <directive + module="mod_authnz_fcgi">AuthnzFcgiDefineProvider</directive>. La + directive <directive + module="mod_authnz_fcgi">AuthnzFcgiCheckAuthnProvider</directive> + permet de l'invoquer. Exemple d'application : +<highlight language="perl"> +#!/usr/bin/perl +use FCGI; +my $request = FCGI::Request(); +while ($request->Accept() >= 0) { + die if $ENV{'FCGI_APACHE_ROLE'} ne "AUTHENTICATOR"; + die if $ENV{'FCGI_ROLE'} ne "AUTHORIZER"; + + # This authorizer assumes that the RequireBasicAuth option of + # AuthnzFcgiCheckAuthnProvider is On: + die if !$ENV{'REMOTE_PASSWD'}; + die if !$ENV{'REMOTE_USER'}; + + print STDERR "This text is written to the web server error log.\n"; + + if ( ($ENV{'REMOTE_USER' } eq "foo" || $ENV{'REMOTE_USER'} eq "foo1") && + $ENV{'REMOTE_PASSWD'} eq "bar" ) { + print "Status: 200\n"; + print "Variable-AUTHNZ_1: authnz_01\n"; + print "Variable-AUTHNZ_2: authnz_02\n"; + print "\n"; + } + else { + print "Status: 401\n\n"; + # If a response body is written here, it will be returned to + # the client. + } +} +</highlight> + + Exemple de configuration httpd : +<highlight language="config"> +AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10103/ +<Location "/protected/"> + AuthType ... + AuthName ... + AuthnzFcgiCheckAuthnProvider FooAuthn \ + Authoritative On \ + RequireBasicAuth Off \ + UserExpr "%{reqenv:REMOTE_USER}" + Require ... +</Location> +</highlight> + </dd> + + </dl> + +</section> + +<section id="examples"><title>Exemples supplémentaires</title> + + <ol> + <li>Si votre application supporte séparément les rôles + d'authentification et d'autorisation (<code>AUTHENTICATOR</code> et + <code>AUTHORIZER</code>), vous pouvez définir des fournisseurs + séparés comme suit, même s'ils correspondent à la même application : + +<highlight language="config"> +AuthnzFcgiDefineProvider authn FooAuthn fcgi://localhost:10102/ +AuthnzFcgiDefineProvider authz FooAuthz fcgi://localhost:10102/ +</highlight> + + Spécifie le fournisseur authn via la directive + <directive module="mod_auth_basic">AuthBasicProvider</directive> + et le fournisseur authz via la directive + <directive module="mod_authz_core">Require</directive>: + +<highlight language="config"> +AuthType Basic +AuthName "Restricted" +AuthBasicProvider FooAuthn +Require FooAuthz +</highlight> + </li> + + <li>Si votre application supporte le rôle générique + <code>AUTHORIZER</code> (authentification et autorisation en une + seule invocation), vous pouvez définir un fournisseur unique comme + suit : + +<highlight language="config"> +AuthnzFcgiDefineProvider authnz FooAuthnz fcgi://localhost:10103/ +</highlight> + + Spécifie le fournisseur authnz via les directives + <directive>AuthBasicProvider</directive> et + <directive>Require</directive> : + +<highlight language="config"> +AuthType Basic +AuthName "Restricted" +AuthBasicProvider FooAuthnz +Require FooAuthnz +</highlight> + </li> +</ol> +</section> + +<section id="limitations"><title>Limitations</title> + + <p>Les fonctionnalités suivantes ne sont pas encore implémentées :</p> + + <dl> + <dt>Vérificateur d'accès d'Apache httpd</dt> + <dd>La phase <em>access check</em> de l'API Apache httpd est + distincte des phases d'authentification et d'autorisation. + Certaines autres implémentations de FastCGI supportent cette phase + et lorsque c'est le cas, la variable <code>FCGI_APACHE_ROLE</code> + est définie à <code>ACCESS_CHECKER</code>.</dd> + + <dt>Redirections (pipes) ou sockets locaux (Unix)</dt> + <dd>Seuls les sockets TCP sont actuellement supportés.</dd> + + <dt>Support de mod_authn_socache</dt> + <dd>Le support de l'interaction avec mod_authn_socache pour les + applications qui interviennent dans le processus + d'authentification d'Apache httpd serait souhaitable.</dd> + + <dt>Support de l'authentification de type digest à l'aide de AuthDigestProvider</dt> + <dd>Cette limitation ne sera probablement jamais franchie car il + n'existe aucun flux de données d'autorisation capable de lire dans + un condensé de type hash.</dd> + + <dt>Gestion des processus applicatifs</dt> + <dd>Cette fonctionnalité restera probablement hors de portée de ce + module. Il faudra donc gérer les processus applicatifs d'une autre + manière ; par exemple, <program>fcgistarter</program> permet de + les démarrer.</dd> + + <dt>AP_AUTH_INTERNAL_PER_URI</dt> + <dd>Tous les fournisseurs sont actuellement enregistrés en tant + que AP_AUTH_INTERNAL_PER_CONF, ce qui signifie que les + vérifications ne sont pas effectuées pour les + sous-requêtes internes avec la même configuration de contrôle + d'accès que la requête initiale.</dd> + + <dt>Conversion du jeu de caractères des données de protocole</dt> + <dd>Si mod_authnz_fcgi s'exécute dans un environnement de + compilation EBCDIC, toutes les données de protocole FastCGI sont + écrites en EBCDIC et doivent être disponibles en EBCDIC.</dd> + + <dt>Plusieurs requêtes pour une connexion</dt> + <dd>Actuellement, la connexion au fournisseur d'autorisation + FastCGI est fermée après chaque phase de traitement. Par exemple, + si le fournisseur d'autorisation gère séparément les phases + <em>authn</em> et <em>authz</em>, deux connexions seront + nécessaires.</dd> + + <dt>Redirection de certains URIs</dt> + <dd>Les URIs en provenance des clients ne peuvent pas être + redirigés selon une table de redirection, comme avec la directive + <directive>ProxyPass</directive> utilisée avec les répondeurs + FastCGI.</dd> + + </dl> + +</section> + +<section id="logging"><title>Journalisation</title> + + <ol> + <li>Les erreurs de traitement sont journalisées à un niveau + <code>error</code> ou supérieur.</li> + <li>Les messages envoyés par l'application sont journalisés au + niveau <code>warn</code>.</li> + <li>Les messages de deboguage à caractère général sont + journalisés au niveau <code>debug</code>.</li> + <li>Les variables d'environnement transmises à l'application + sont journalisées au niveau <code>trace2</code>. La valeur de la + variable <code>REMOTE_PASSWD</code> sera occultée, mais + <strong>toute autre donnée sensible sera visible dans le + journal</strong>.</li> + <li>Toutes les entrées/sorties entre le module et l'application + FastCGI, y compris les variables d'environnement, seront + journalisées au format imprimable et hexadécimal au niveau + <code>trace5</code>. <strong>Toutes les données sensibles seront + visibles dans le journal.</strong></li> + </ol> + + <p>La directive <directive module="core">LogLevel</directive> permet + de configurer un niveau de journalisation spécifique à + mod_authnz_fcgi. Par exemple :</p> + +<highlight language="config"> +LogLevel info authnz_fcgi:trace8 +</highlight> + +</section> + +<directivesynopsis> +<name>AuthnzFcgiDefineProvider</name> +<description>Définit une application FastCGI en tant que fournisseur +d'authentification et/ou autorisation</description> +<syntax>AuthnzFcgiDefineProvider <em>type</em> <em>provider-name</em> +<em>backend-address</em></syntax> +<default>none</default> +<contextlist><context>server config</context></contextlist> +<usage> + <p>Cette directive permet de définir une application FastCGI en tant + que fournisseur pour une phase particulière d'authentification ou + d'autorisation.</p> + + <dl> + <dt><em>type</em></dt> + <dd>Les valeurs de ce paramètre sont <em>authn</em> pour + l'authentification, <em>authz</em> pour l'autorisation, ou + <em>authnz</em> pour un fournisseur d'autorisation générique + FastCGI qui effectue les deux vérifications.</dd> + + <dt><em>provider-name</em></dt> + <dd>Ce paramètre permet d'associer un nom au fournisseur ; ce nom + pourra être utilisé dans des directives comme <directive + module="mod_auth_basic">AuthBasicProvider</directive> et + <directive module="mod_authz_core">Require</directive>.</dd> + + <dt><em>backend-address</em></dt> + <dd>Ce paramètre permet de spécifier l'adresse de l'application + sous la forme <em>fcgi://hostname:port/</em>. Le ou les processus + de l'application doivent être gérés indépendamment comme avec + <program>fcgistarter</program>.</dd> + </dl> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>AuthnzFcgiCheckAuthnProvider</name> +<description>Permet à une application FastCGI de gérer l'accroche +d'authentification check_authn.</description> +<syntax>AuthnzFcgiCheckAuthnProvider <em>provider-name</em>|<code>None</code> +<em>option</em> ...</syntax> +<default>none</default> +<contextlist><context>directory</context></contextlist> +<override>FileInfo</override> +<usage> + <p>Cette directive permet de confier à une application FastCGI la + gestion d'une phase spécifique du processus d'authentification ou + d'autorisation.</p> + + <p>Certaines fonctionnalités des fournisseurs d'autorisation FastCGI + nécessitent cette directive en lieu et place de + <directive>AuthBasicProvider</directive> pour pouvoir être activées :</p> + + <ul> + <li>L'authentification de type autre que basique ; en général, + détermination de l'identifiant utilisateur et renvoi de sa valeur + depuis le fournisseur d'autorisation ; voir l'option + <code>UserExpr</code> ci-dessous</li> + <li>Sélection d'un code de réponse personnalisé ; en cas de + code de réponse autre que 200 en provenance du fournisseur + d'autorisation, c'est ce code qui sera utilisé comme code d'état + de la réponse</li> + <li>Définition du corps d'une réponse autre que 200 ; si le + fournisseur d'autorisation renvoie un corps de réponse avec un + code autre que 200, c'est ce corps de réponse qui sera renvoyé au + client ; la longueur du texte est limitée à 8192 octets</li> + </ul> + + <dl> + <dt><em>provider-name</em></dt> + <dd>C'est le nom du fournisseur défini au préalable via la + directive <directive>AuthnzFcgiDefineProvider</directive>.</dd> + + <dt><code>None</code></dt> + <dd>Spécifiez <code>None</code> pour désactiver un fournisseur + activé avec cette même directive dans une autre portée, par + exemple dans un répertoire parent.</dd> + + <dt><em>option</em></dt> + <dd>Les options suivantes sont supportées : + + <dl> + <dt>Authoritative On|Off (par défaut On)</dt> + <dd>Cette option permet de définir si l'appel à d'autres + modules est autorisé lorsqu'un fournisseur d'autorisation FastCGI a + été configuré et si la requête échoue.</dd> + + <dt>DefaultUser <em>id utilisateur</em></dt> + <dd>Lorsque le fournisseur d'autorisation donne son accord, et + si <code>UserExpr</code> est défini et correspond à une chaîne + vide, (par exemple, si le fournisseur d'autorisation ne renvoie + aucune variable), c'est cette valeur qui sera utilisée comme id + utilisateur par défaut. Cela se produit souvent lorsqu'on se trouve dans + un contexte d'invité, ou d'utilisateur non authentifié ; + les utilisateurs et invités se voient alors attribué un id + utilisateur spécifique qui permettra de se connecter et + d'accéder à certaines ressources.</dd> + + <dt>RequireBasicAuth On|Off (par défaut Off)</dt> + <dd>Cette option permet de définir si l'authentification + basique est requise avant de transmettre la requête au + fournisseur d'autorisation. Dans l'affirmative, le fournisseur + d'autorisation ne sera invoqué qu'en présence d'un id + utilisateur et d'un mot de passe ; si ces deux éléments ne sont + pas présents, un code d'erreur 401 sera renvoyé</dd> + + <dt>UserExpr <em>expr</em> (pas de valeur par défaut)</dt> + <dd>Lorsque le client ne fournit pas l'authentification basique + et si le fournisseur d'autorisation détermine l'id utilisateur, + cette expression, évaluée après l'appel au fournisseur + d'autorisation, permet de déterminer l'id utilisateur. Cette + expression se conforme à la <a href="../expr.html">syntaxe + ap_expr</a> et doit correspondre à une chaîne de caractères. + Une utilisation courante consiste à référencer la définition + d'une <code>Variable-<em>XXX</em></code> renvoyée par le + fournisseur d'autorisation via une option du style + <code>UserExpr "%{reqenv:<em>XXX</em>}"</code>. Si cette option + est spécifiée, et si l'id utilisateur ne peut pas être définie + via l'expression après une authentification réussie, la requête + sera rejetée avec un code d'erreur 500.</dd> + + </dl> + </dd> + </dl> +</usage> +</directivesynopsis> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_authnz_fcgi.xml.meta b/docs/manual/mod/mod_authnz_fcgi.xml.meta index 9ce87949f2..0bb1414049 100644 --- a/docs/manual/mod/mod_authnz_fcgi.xml.meta +++ b/docs/manual/mod/mod_authnz_fcgi.xml.meta @@ -8,5 +8,6 @@ <variants> <variant>en</variant> + <variant>fr</variant> </variants> </metafile> diff --git a/docs/manual/mod/mod_brotli.xml.fr b/docs/manual/mod/mod_brotli.xml.fr new file mode 100644 index 0000000000..d5eda396b8 --- /dev/null +++ b/docs/manual/mod/mod_brotli.xml.fr @@ -0,0 +1,321 @@ +<?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 : 1816992 --> +<!-- 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_brotli.xml.meta"> + +<name>mod_brotli</name> +<description>Compression du contenu via Brotli avant sa livraison au client</description> +<status>Extension</status> +<sourcefile>mod_brotli.c</sourcefile> +<identifier>brotli_module</identifier> +<compatibility>Disponible à partir de la version 2.4.26 du serveur HTTP Apache</compatibility> + +<summary> + <p>Le module <module>mod_brotli</module> fournit le filtre en sortie + <code>BROTLI_COMPRESS</code> 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 à <a + href="https://github.com/google/brotli">https://github.com/google/brotli</a>.</p> +</summary> +<seealso><a href="../filter.html">Filters</a></seealso> + +<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 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".</p> + </note> + <p>Voici une configuration simple qui compresse des types de contenus + courants au format texte :</p> + + <example><title>Compression de certains types seulement</title> + <highlight language="config"> +AddOutputFilterByType BROTLI_COMPRESS 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 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".</p> + </note> + + <section id="output"><title>Compression en sortie</title> + <p>La compression est implémentée par le <a + href="../filter.html">filtre</a> <code>BROTLI_COMPRESS</code>. La + directive suivante active la compression pour les documents correspondant + au conteneur dans lequel elle est placée :</p> + + <highlight language="config"> +SetOutputFilter BROTLI_COMPRESS +SetEnvIfNoCase Request_URI \.(?:gif|jpe?g|png)$ no-brotli + </highlight> + + <p>Si vous voulez restreindre la compression à certains types MIME + particuliers, vous pouvez utiliser la directive <directive + module="mod_filter">AddOutputFilterByType</directive>. Dans l'exemple + suivant, l'activation de la compression est restreinte aux fichiers html + de la documentation d'Apache :</p> + + <highlight language="config"> +<Directory "/your-server-root/manual"> + AddOutputFilterByType BROTLI_COMPRESS text/html +</Directory> + </highlight> + + <note><title>Note</title> + Le filtre <code>BROTLI_COMPRESS</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> + Définie via <directive module="mod_env">SetEnv</directive>, la variable + d'environnement <code>no-brotli</code> 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. + </note> + + </section> + +</section> + +<section id="proxies"><title>Interaction avec les serveurs mandataires</title> + + <p>Le module <module>mod_brotli</module> envoie un en-tête de réponse HTTP + <code>Vary:Accept-Encoding</code> 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 <code>Accept-Encoding</code> approprié. Ceci permet + d'éviter d'envoyer du contenu compressé à un client qui ne sera pas en + mesure de le décompresser.</p> + + <p>Si vous utilisez des exclusions spéciales dépendant, par exemple, de + l'en-tête <code>User-Agent</code>, vous devez faire un ajout manuel à + l'en-tête <code>Vary</code> afin d'informer les mandataires des restrictions + supplémentaires. Par exemple, dans une configuration typique où l'addition + du filtre <code>BROTLI_COMPRESS</code> dépend de l'en-tête <code>User-Agent</code>, + vous devez ajouter :</p> + + <highlight language="config"> +Header append Vary User-Agent + </highlight> + + <p>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 <code>*</code> à l'en-tête + <code>Vary</code>. Ceci permet d'éviter que des mandataires qui le + supportent n'effectuent une mise en cache intégrale.</p> + + <example><title>Exemple</title> + <highlight language="config"> +Header set Vary * + </highlight> + </example> +</section> + +<section id="precompressed"><title>Servir un contenu pré-compressé</title> + + <p>comme <module>mod_brotli</module> 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 :</p> + + <highlight language="config"> +<IfModule mod_headers.c> + # Sert des fichiers CSS et JS compressés par brotli, s'ils existent + # et si le client supporte brotli. + RewriteCond "%{HTTP:Accept-encoding}" "br" + RewriteCond "%{REQUEST_FILENAME}\.br" "-s" + RewriteRule "^(.*)\.(js|css)" "$1\.$2\.br" [QSA] + + # Sert des types de contenu corrects, et évite la double compression. + RewriteRule "\.css\.gz$" "-" [T=text/css,E=no-brotli:1] + RewriteRule "\.js\.gz$" "-" [T=text/javascript,E=no-brotli: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> + </highlight> + +</section> + +<directivesynopsis> +<name>BrotliFilterNote</name> +<description>Enregistre le taux de compression dans une note à des fins de +journalisation</description> +<syntax>BrotliFilterNote [<var>type</var>] <var>notename</var></syntax> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>La directive <directive>BrotliFilterNote</directive> permet d'indiquer + qu'une note à propos du taux de compression doit être attachée à la + requête. L'argument <var>notename</var> permet de spécifier le nom de la + note. Vous pouvez utiliser cette note à des fins de statistiques en ajoutant + l'information correspondante à votre <a href="../logs.html#accesslog">access + log</a>.</p> + + <example><title>Exemple</title> + <highlight language="config"> +BrotliFilterNote ratio + +LogFormat '"%r" %b (%{ratio}n) "%{User-agent}i"' brotli +CustomLog "logs/brotli_log" brotli + </highlight> + </example> + + <p>Si vous souhaitez que l'information enregistrée dans vos journaux soit + plus pertinente, vous pouvez renseigner l'argument optionnel <var>type</var> + afin de spécifier le type de données à enregistrer dans la note à + journaliser. L'argument <var>type</var> accepte les valeurs suivantes :</p> + + <dl> + <dt><code>Input</code></dt> + <dd>Enregistre dans la note le nombre d'octets contenus dans le flux + d'entrée du filtre.</dd> + + <dt><code>Output</code></dt> + <dd>Enregistre dans la note le nombre d'octets contenus dans le flux + de sortie du filtre.</dd> + + <dt><code>Ratio</code></dt> + <dd>Enregistre dans la note le taux de compression (<code>output/input * + 100</code>). Il s'agit de l'option par défaut si l'argument + <var>type</var> est omis.</dd> + </dl> + + <p>Vous pouvez alors configurer vos journaux de la manière suivante :</p> + + <example><title>Journalisation spécifique</title> + <highlight language="config"> +BrotliFilterNote Input instream +BrotliFilterNote Output outstream +BrotliFilterNote Ratio ratio + +LogFormat '"%r" %{outstream}n/%{instream}n (%{ratio}n%%)' brotli +CustomLog "logs/brotli_log" brotli + </highlight> + </example> +</usage> +<seealso><module>mod_log_config</module></seealso> +</directivesynopsis> + +<directivesynopsis> +<name>BrotliCompressionQuality</name> +<description>Qualité de la compression</description> +<syntax>BrotliCompressionQuality <var>value</var></syntax> +<default>BrotliCompressionQuality 5</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>La directive <directive>BrotliCompressionQuality</directive> 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. + </p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>BrotliCompressionWindow</name> +<description>Taille de la fenêtre de compression glissante brotli</description> +<syntax>BrotliCompressionWindow <var>value</var></syntax> +<default>BrotliCompressionWindow 18</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>La directive <directive>BrotliCompressionWindow</directive> 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.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> + +<name>BrotliCompressionMaxInputBlock</name> +<description>Taille maximale du bloc de données en entrée</description> +<syntax>BrotliCompressionMaxInputBlock <var>value</var></syntax> +<default>(automatic)</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>La directive <directive>BrotliCompressionMaxInputBlock</directive> 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.</p> +</usage> +</directivesynopsis> + +<directivesynopsis> +<name>BrotliAlterETag</name> +<description>Comment l'en-tête de réponse ETag doit être modifié au cours de la +compression</description> +<syntax>BrotliAlterETag AddSuffix|NoChange|Remove</syntax> +<default>BrotliAlterETag AddSuffix</default> +<contextlist><context>server config</context><context>virtual host</context> +</contextlist> + +<usage> + <p>La directive <directive>BrotliAlterETag</directive> permet d'indiquer + 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 ETag, ce qui + implique que les représentations compressées et non compressées possèderont + des en-têtes ETag uniques. C'était 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.</p></dd> + <dt>NoChange</dt> + <dd><p>Ne modifie pas l'en-tête ETag d'une réponse compressée. C'était le + comportement par défaut depuis 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.</p></dd> + <dt>Remove</dt> + <dd><p>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.</p></dd> + </dl> +</usage> +</directivesynopsis> + +</modulesynopsis> diff --git a/docs/manual/mod/mod_brotli.xml.meta b/docs/manual/mod/mod_brotli.xml.meta index 8dc14b10a5..8c6376e8a0 100644 --- a/docs/manual/mod/mod_brotli.xml.meta +++ b/docs/manual/mod/mod_brotli.xml.meta @@ -8,5 +8,6 @@ <variants> <variant>en</variant> + <variant>fr</variant> </variants> </metafile> |