granicus.if.org Git - apache/blob - docs/manual/mod/mod_proxy_fcgi.xml.fr

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.fr.xsl"?>
   4 <!-- English Revision: 1823832 -->
   5 <!-- French translation : Lucien GENTIS -->
   6
   7 <!--
   8  Licensed to the Apache Software Foundation (ASF) under one or more
   9  contributor license agreements.  See the NOTICE file distributed with
  10  this work for additional information regarding copyright ownership.
  11  The ASF licenses this file to You under the Apache License, Version 2.0
  12  (the "License"); you may not use this file except in compliance with
  13  the License.  You may obtain a copy of the License at
  14
  15      http://www.apache.org/licenses/LICENSE-2.0
  16
  17  Unless required by applicable law or agreed to in writing, software
  18  distributed under the License is distributed on an "AS IS" BASIS,
  19  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  20  See the License for the specific language governing permissions and
  21  limitations under the License.
  22 -->
  23
  24 <modulesynopsis metafile="mod_proxy_fcgi.xml.meta">
  25
  26 <name>mod_proxy_fcgi</name>
  27 <description>Module fournissant le support de FastCGI à
  28 <module>mod_proxy</module></description>
  29 <status>Extension</status>
  30 <sourcefile>mod_proxy_fcgi.c</sourcefile>
  31 <identifier>proxy_fcgi_module</identifier>
  32 <compatibility>Disponible depuis la version 2.3 d'Apache</compatibility>
  33
  34 <summary>
  35     <p>Pour fonctionner, ce module <em>nécessite</em> le chargement de
  36     <module>mod_proxy</module>. Il fournit le support du protocole <a
  37     href="http://www.fastcgi.com/">FastCGI</a>.</p>
  38
  39     <p>Ainsi, pour pouvoir traiter le protocole <code>FastCGI</code>,
  40     <module>mod_proxy</module> et <module>mod_proxy_fcgi</module>
  41     doivent être chargés dans le serveur.</p>
  42
  43     <p>A la différence de <a
  44     href="http://httpd.apache.org/mod_fcgid/">mod_fcgid</a> et <a
  45     href="http://www.fastcgi.com/">mod_fastcgi</a>,
  46     <module>mod_proxy_fcgi</module> n'est pas en mesure de démarrer le
  47     processus de l'application ; <program>fcgistarter</program> est
  48     fourni à cet effet sur certaines plateformes. Le framework
  49     applicatif FastCGI utilisé peut aussi fournir la gestion des
  50     processus ou des lancements de programmes externes.</p>
  51
  52     <note type="warning"><title>Avertissement</title>
  53       <p>N'activez pas la fonctionnalité de mandataire avant d'avoir <a
  54       href="mod_proxy.html#access">sécurisé votre serveur</a>. Les
  55       serveurs mandataires ouverts sont dangereux non seulement pour
  56       votre réseau, mais aussi pour l'Internet au sens large.</p>
  57     </note>
  58 </summary>
  59
  60 <seealso><program>fcgistarter</program></seealso>
  61 <seealso><module>mod_proxy</module></seealso>
  62 <seealso><module>mod_authnz_fcgi</module></seealso>
  63
  64 <section id="examples"><title>Exemples</title>
  65     <p>Pour que ces exemples fonctionnent, vous ne devez pas oublier
  66     d'activer <module>mod_proxy</module> et
  67     <module>mod_proxy_fcgi</module>.</p>
  68
  69     <example><title>Instance d'application unique</title>
  70     <highlight language="config">
  71 ProxyPass "/mon_appli/" "fcgi://localhost:4000/"
  72       </highlight>
  73     </example>
  74
  75
  76     <p><module>mod_proxy_fcgi</module> interdisant par défaut la
  77     réutilisation des connexions, lorsqu'une requête a été traitée, la
  78     connexion ne sera pas maintenue ouverte par le processus enfant
  79     httpd, et ne sera donc pas réutilisée. Cependant, si l'application
  80     FastCGI supporte les connexions httpd simultanées, vous pouvez opter
  81     pour la réutilisation des connexions comme dans l'exemple suivant :</p>
  82
  83     <example><title>Instance d'application unique, réutilisation
  84     des connexions (versions 2.4.11 et supérieures)</title>
  85     <highlight language="config">
  86   ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on
  87     </highlight>
  88     </example>
  89
  90     <note><title>Active la réutilisation des connexions vers un serveur FCGI
  91     d'arrière-plan tel que PHP-FPM</title>
  92     <p>Il faut garder à l'esprit que PHP-FPM (en février 2018) utilise un modèle
  93     du style prefork ; autrement dit, chacun de ses processus de travail ne peut
  94     gérer qu'une connexion à la fois.<br /> Par défaut, lorsqu'il est configuré
  95     avec <code>enablereuse=on</code> et lorsqu'un MPM à base de threads est
  96     utilisé (comme <module>worker</module> ou <module>event</module>), mod_proxy
  97     autorise un jeu de <directive
  98     module="mpm_common">ThreadsPerChild</directive> connexions vers le serveur
  99     d'arrière-plan pour chaque processus httpd, et par conséquent, il faut
 100     prêter une attention particulière aux situations suivantes :</p>
 101     <ul>
 102       <li>Avec une charge en HTTP/1, il est fort probable que le nombre de
 103       connexions vers le serveur FCGI d'arrière-plan augmente jusqu'à atteindre
 104       <directive module="mpm_common">MaxRequestWorkers</directive>.</li>
 105       <li>Avec une charge en HTTP/2, et vue la manière dont
 106       <module>mod_http2</module> est implémenté, il y a des threads de travail
 107       h2 additionnels qui peuvent forcer la création de connexions
 108       supplémentaires vers le serveur d'arrière-plan. Le nombre total de
 109       connexions que contiennent les jeux de connexions peut alors dépasser
 110       <directive module="mpm_common">MaxRequestWorkers</directive>.</li>
 111     </ul>
 112     <p>Le nombre maximum de processus de travail PHP-FPM doit être défini
 113     judicieusement car il est possible qu'ils finissent par rester dans l'état
 114     occupé ("busy") pour ne gérer que des connexions persistantes inactives,
 115     sans avoir la possibilité d'en établir de nouvelles ; ce qui se traduira
 116     pour l'utilisateur final par une pile de "HTTP request timeouts".</p>
 117     </note>
 118
 119     <p>Dans l'exemple suivant, l'URI de la requête est transmis en tant
 120     que chemin du système de fichiers pour l'exécution du démon PHP-FPM.
 121     L'URL de la requête est implicitement ajoutée au second paramètre.
 122     PHP-FPM est à l'écoute de l'hôte et du port qui
 123     suivent fcgi://. La conservation/réutilisation des connexions est activée.</p>
 124     <example><title>PHP-FPM</title>
 125     <highlight language="config">
 126 ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on
 127     </highlight>
 128     </example>
 129
 130     <p>Dans l'exemple suivant, l'URI de la requête est transmis en tant
 131     que chemin du système de fichiers pour l'exécution du démon PHP-FPM.
 132     Dans ce cas cependant, PHP-FPM est à l'écoute d'un socket de domaine
 133     unix (UDS). Cette fonctionnalité est disponible à partir de la
 134     version 2.4.9. Avec cette syntaxe, si un nom d'hôte et un port sont
 135     ajoutés après fcgi://, ils seront ignorés.</p>
 136     <example><title>PHP-FPM with UDS</title>
 137     <highlight language="config">
 138 ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"
 139     </highlight>
 140     </example>
 141
 142     <p>Dans l'exemple suivant, on force le module à traiter les paquets de
 143     données en provenance du serveur FCGI d'arrière-plan dès leur réception, sans les
 144     faire transiter par un tampon.
 145     </p>
 146     <example><title>Force le traitement des données FCGI sans mise en tampon</title>
 147     <highlight language="config">
 148 ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on flushpackets=on
 149     </highlight>
 150     </example>
 151
 152     <p>L'exemple suivant est similaire au précédent avec une différence : ici,
 153     les données en provenance du serveur FCGI d'arrière-plan sont traitées après un
 154     temps de valeur fixe (elles sont mises en tampon). Cette méthode est
 155     utile si le serveur FCGI d'arrière-plan envoie ses données sous forme
 156     de petits paquets, auquel cas le traitement immédiat de chacun d'entre eux
 157     serait inefficace et couteux en ressources. Notez que cet exemple ne sera
 158     peut-être pas adapté dans le cas où l'envoi de paquets de données par
 159     l'application FCGI est bloqué par l'attente de données en provenance du
 160     client.
 161     </p>
 162     <example><title>Force le traitement des données FCGI après une mise en
 163     tampon de 20ms</title>
 164     <highlight language="config">
 165 ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" flushpackets=on flushwait=20
 166     </highlight>
 167     </example>
 168
 169     <p>La passerelle à répartition de charge nécessite le chargement du
 170     module <module>mod_proxy_balancer</module> et d'au moins un module
 171     fournissant un algorithme de répartition de charge, comme
 172     <module>mod_lbmethod_byrequests</module> en plus des modules
 173     déjà cités. <module>mod_lbmethod_byrequests</module> est le module
 174     par défaut et sera utilisé dans cet exemple de configuration.</p>
 175
 176     <example><title>Passerelle à répartition de charge vers plusieurs
 177     instances de l'application</title>
 178     <highlight language="config">
 179 ProxyPass "/myapp/" "balancer://myappcluster/"
 180 &lt;Proxy "balancer://myappcluster/"&gt;
 181     BalancerMember "fcgi://localhost:4000"
 182     BalancerMember "fcgi://localhost:4001"
 183 &lt;/Proxy&gt;
 184     </highlight>
 185     </example>
 186
 187     <p>Vous pouvez aussi forcer le traitement d'une requête en tant que
 188     requête de mandataire inverse en créant un court-circuiteur de
 189     gestionnaire approprié. Dans l'exemple ci-dessous, toutes les
 190     requêtes pour des scripts PHP seront transmises au serveur FastCGI
 191     spécifié par mandat inverse. Cette fonctionnalité est disponible à
 192     partir de la version 2.4.10 du serveur HTTP Apache. Pour des raisons
 193     de performances, il est recommandé de définir un <a
 194     href="mod_proxy.html#workers">worker (configuration d'un
 195     mandataire)</a> représentant le même serveur fcgi:// d'arrière-plan.
 196     Avec cette configuration, il est possible d'effectuer une
 197     correspondance directe entre l'URI et le chemin du fichier sur le
 198     serveur, et le chemin local du fichier sera alors transmis au serveur
 199     d'arrière-plan. Lorsque FastCGI est configuré ainsi, le serveur est
 200     en mesure de calculer le PATH_INFO le plus approprié.
 201       </p>
 202         <example><title>Mandataire via un gestionnaire</title>
 203       <highlight language="config">
 204 &lt;FilesMatch "\.php$"&gt;
 205     # Note : la seule partie variable est /path/to/app.sock
 206     SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
 207 &lt;/FilesMatch&gt;
 208    # Définition d'une configuration de mandataire qui convient.
 209    # La partie qui est mise en correspondance avec la valeur de
 210    # SetHandler est la partie qui suit le "pipe". Si vous devez faire
 211    # une distinction, "localhost" peut être changé en un nom de serveur
 212    # unique.
 213    &lt;Proxy "fcgi://localhost/" enablereuse=on max=10&gt;
 214    &lt;/Proxy&gt;
 215
 216 &lt;FilesMatch ...&gt;
 217     SetHandler  "proxy:fcgi://localhost:9000"
 218 &lt;/FilesMatch&gt;
 219
 220 &lt;FilesMatch ...&gt;
 221     SetHandler  "proxy:balancer://myappcluster/"
 222 &lt;/FilesMatch&gt;
 223       </highlight>
 224    </example>
 225 </section>
 226
 227 <section id="env"><title>Variables d'environnement</title>
 228     <p>En plus des directives de configuration qui contrôlent le
 229     comportement de <module>mod_proxy</module>, de nombreuses
 230     <dfn>variables d'environnement</dfn> permettent de piloter le
 231     fournisseur du protocole FCGI :</p>
 232     <dl>
 233         <dt>proxy-fcgi-pathinfo</dt>
 234         <dd>Lorsqu'il est configuré via les directives <directive
 235         module="mod_proxy">ProxyPass</directive> ou <directive
 236         module="mod_proxy">ProxyPassMatch</directive>,
 237         <module>mod_proxy_fcgi</module> ne définit pas la variable
 238         d'environnement <var>PATH_INFO</var>,
 239         ce qui permet au serveur FCGI d'arrière-plan de déterminer
 240         correctement <var>SCRIPT_NAME</var> et <var>Script-URI</var>, et
 241         de se conformer à la section 3.3 de la RFC 3875. Si au contraire
 242         vous avez souhaitez que <module>mod_proxy_fcgi</module> génère une
 243         "estimation la plus exacte possible" de <var>PATH_INFO</var>,
 244         définissez la variable d'environnement
 245         <var>proxy-fcgi-pathinfo</var>. Ceci peut servir de
 246         contournement pour une bogue présente dans certaines
 247         implémentations de FCGI. Cette variable peut être
 248         multivaluée afin de pouvoir choisir la valeur la plus appropriée
 249         (versions 2.4.11 et supérieures) :
 250         <dl>
 251           <dt>first-dot</dt>
 252           <dd>PATH_INFO est extrait à partir du slash qui suit le
 253           <em>premier</em> "." de l'URL.</dd>
 254           <dt>last-dot</dt>
 255           <dd>PATH_INFO est extrait à partir du slash qui suit le
 256           <em>dernier</em> "." de l'URL.</dd>
 257           <dt>full</dt>
 258           <dd>PATH_INFO est calculé en supposant que l'URL correspond au
 259           chemin du système de fichiers.</dd>
 260           <dt>unescape</dt>
 261           <dd>PATH_INFO correspond à la partie chemin de l'URL avec ses
 262           séquences d'échappement décodées.</dd>
 263           <dt>toute autre valeur</dt>
 264           <dd>PATH_INFO correspond à la partie chemin de l'URL.
 265               Auparavant, c'était la seule option pour proxy-fcgi-pathinfo.</dd>
 266          </dl>
 267         </dd>
 268     </dl>
 269 </section>
 270
 271 <directivesynopsis>
 272 <name>ProxyFCGIBackendType</name>
 273 <description>Spécifie le type de l'application FastCGI d'arrière-plan</description>
 274 <syntax>ProxyFCGIBackendType FPM|GENERIC</syntax>
 275 <default>ProxyFCGIBackendType FPM</default>
 276 <contextlist><context>server config</context>
 277 <context>virtual host</context><context>directory</context>
 278 <context>.htaccess</context></contextlist>
 279 <override>FileInfo</override>
 280 <compatibility>Disponible à partir de la version 2.4.26 du serveur HTTP Apache</compatibility>
 281
 282 <usage>
 283 <p>Cette directive permet de spécifier le type de l'application FastCGI
 284 d'arrière-plan. Certains serveurs FastCGI, comme PHP-FPM, utilisent de manière
 285 historique des variables d'environnement exotiques pour identifier le type du
 286 serveur mandataire utilisé. Définissez cette directive à "GENERIC" si votre
 287 application n'est pas de type PHP-FPM et n'interpréter pas correctement des
 288 variables d'environnement comme SCRIPT_FILENAME ou PATH_TRANSLATED telles
 289 qu'elles sont définies par le serveur.</p>
 290
 291 <p>SCRIPT_FILENAME est un exemple de valeur modifiée par la définition de cette
 292 directive. Historiquement, lorsqu'on utilisait le module
 293 <module>mod_proxy_fcgi</module>, SCRIPT_FILENAME était préfixé par la chaîne
 294 "proxy:fcgi://". C'est cette variable que lisent certaines applications FastCGI
 295 génériques en tant que valeur en entrée pour leur script ; cependant, PHP-FPM
 296 peut supprimer le préfixe, puis garder en mémoire qu'il communique avec Apache.
 297 Avec les versions 2.4.21 à 2.4.25, ce préfixe était automatiquement supprimé par
 298 le serveur, empêchant ainsi PHP-FPM de détecter et interopérer avec Apache dans
 299 certains scénarios.</p>
 300 </usage>
 301 </directivesynopsis>
 302
 303 <directivesynopsis>
 304 <name>ProxyFCGISetEnvIf</name>
 305 <description>Permet d'adapter la valeur des variables envoyées aux serveurs
 306 FastCGI</description>
 307 <syntax>ProxyFCGISetEnvIf <var>conditional-expression</var>
 308     [!]<var>environment-variable-name</var>
 309     [<var>value-expression</var>]</syntax>
 310 <contextlist><context>server config</context>
 311 <context>virtual host</context><context>directory</context>
 312 <context>.htaccess</context></contextlist>
 313 <override>FileInfo</override>
 314 <compatibility>Disponible à partir de la version 2.4.26 du serveur HTTP Apache.</compatibility>
 315
 316 <usage>
 317 <p>Juste avant la transmission d'une requête au serveur FastCGI configuré, le
 318 coeur du programme du serveur web définit un certain nombre de variables
 319 d'environnement en fonction de certains détails de la requête considérée. Les
 320 programmes FastCGI utilisent souvent ces variables comme données en entrée afin
 321 de déterminer quels scripts sous-jacents ils vont exécuter, ou quelles données
 322 en sortie doivent être produites.</p>
 323 <p>Voici quelques exemples de variables d'environnement importantes :</p>
 324 <ul>
 325   <li>SCRIPT_NAME</li>
 326   <li>SCRIPT_FILENAME</li>
 327   <li>REQUEST_URI</li>
 328   <li>PATH_INFO</li>
 329   <li>PATH_TRANSLATED</li>
 330 </ul>
 331
 332 <p>Cette directive permet de passer outre les variables d'environnement
 333 ci-dessus, entre autres. Elle est évaluée après la définition de la valeur
 334 initiale de ces variables ; elle peuvent donc être utilisées comme entrées dans
 335 les expressions définissants les conditions et les valeurs.</p>
 336 <p>Syntaxe des paramètres :</p>
 337 <dl>
 338 <dt>conditional-expression</dt>
 339 <dd>Définit une condition en fonction de laquelle la
 340 variable d'environnement qui suit sera modifiée ou non. Pour la syntaxe de cette
 341 expression, reportez-vous aux exemples qui suivent ou à la spécification
 342 détaillée dans le document <a href="../expr.html">ap_expr</a>.
 343    </dd>
 344 <dt>environment-variable-name</dt>
 345 <dd>Spécifie le nom de la variable d'environnement à modifier, par exemple
 346 PATH_INFO. Si elle est précédée d'un point d'exclamation, la définition de la
 347 variable sera annulée.</dd>
 348 <dt>value-expression</dt>
 349 <dd>Spécifie la nouvelle valeur de la variable "environment-variable-name". On
 350 peut inclure des
 351 références arrières, comme "$1", issues de captures en provenance de
 352 l'expression rationnelle <var>conditional-expression</var>. Si cette valeur est
 353 omise, la variable est définie (ou sa valeur est écrasée) par une chaîne vide
 354 &mdash; voir cependant la note ci-après.</dd>
 355 </dl>
 356
 357 <example>
 358    <highlight language="config">
 359 # Une modification basique, inconditionnelle
 360 ProxyFCGISetEnvIf "true" PATH_INFO "/example"
 361
 362 # Utilisation d'une variable d'environnement pour spécifier la nouvelle valeur
 363 ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"
 364 <br/>
 365 # Utilisation de captures dans la condition et de références arrières dans la
 366 # nouvelle valeur
 367 ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m#(/.*prefix)(\d+)(.*)#" PATH_TRANSLATED "$1$3"
 368    </highlight>
 369 </example>
 370
 371 <note><title>Note : Annulation définition ou valeur vide</title>
 372   La ligne suivante annule la définition de la variable <code>VARIABLE</code>,
 373   ce qui l'empêche d'être envoyée au serveur FastCGI :
 374
 375     <highlight language="config">ProxyFCGISetEnvIf true !VARIABLE</highlight>
 376
 377   La ligne suivante, quant à elle, efface la <em>valeur</em> de la variable
 378   <code>VARIABLE</code> en lui affectant la chaîne vide ; cette variable
 379   <code>VARIABLE</code> sera alors tout de même envoyée au serveur FastCGI :
 380
 381     <highlight language="config">ProxyFCGISetEnvIf true VARIABLE</highlight>
 382
 383   La spécification CGI/1.1 <a
 384   href="https://tools.ietf.org/html/rfc3875#section-4.1">ne fait pas de
 385   distinction</a> entre une variable contenant une chaîne vide et une variable qui
 386   n'existe pas. De nombreuses implémentations CGI et FastCGI font cependant
 387   cette distinction (ou permettent aux scripts de la faire). Le choix de celle
 388   que vous allez utiliser dépend de votre implémentation et de la raison qui
 389   vous pousse à modifier cette variable.
 390 </note>
 391
 392 </usage>
 393 </directivesynopsis>
 394
 395 </modulesynopsis>