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: 1782538:1793934 (outdated) -->
   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     <p>Dans l'exemple suivant, l'URI de la requête est transmis en tant
  91     que chemin du système de fichiers pour l'exécution du démon PHP-FPM.
  92     L'URL de la requête est implicitement ajoutée au second paramètre.
  93     PHP-FPM est à l'écoute de l'hôte et du port qui
  94     suivent fcgi://. La conservation des connexions est activée.</p>
  95     <example><title>PHP-FPM</title>
  96     <highlight language="config">
  97 ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on
  98     </highlight>
  99     </example>
 100
 101     <p>Dans l'exemple suivant, l'URI de la requête est transmis en tant
 102     que chemin du système de fichiers pour l'exécution du démon PHP-FPM.
 103     Dans ce cas cependant, PHP-FPM est à l'écoute d'un socket de domaine
 104     unix (UDS). Cette fonctionnalité est disponible à partir de la
 105     version 2.4.9. Avec cette syntaxe, si un nom d'hôte et un port sont
 106     ajoutés après fcgi://, ils seront ignorés.</p>
 107     <example><title>PHP-FPM with UDS</title>
 108     <highlight language="config">
 109 # A ce jour, UDS ne supporte pas la réutilisation des connexions
 110 ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"
 111     </highlight>
 112     </example>
 113
 114     <p>La passerelle à répartition de charge nécessite le chargement du
 115     module <module>mod_proxy_balancer</module> et d'au moins un module
 116     fournissant un algorithme de répartition de charge, comme
 117     <module>mod_lbmethod_byrequests</module> en plus des modules
 118     déjà cités. <module>mod_lbmethod_byrequests</module> est le module
 119     par défaut et sera utilisé dans cet exemple de configuration.</p>
 120
 121     <example><title>Passerelle à répartition de charge vers plusieurs
 122     instances de l'application</title>
 123     <highlight language="config">
 124 ProxyPass "/myapp/" "balancer://myappcluster/"
 125 &lt;Proxy "balancer://myappcluster/"&gt;
 126     BalancerMember "fcgi://localhost:4000"
 127     BalancerMember "fcgi://localhost:4001"
 128 &lt;/Proxy&gt;
 129     </highlight>
 130     </example>
 131
 132     <p>Vous pouvez aussi forcer le traitement d'une requête en tant que
 133     requête de mandataire inverse en créant un court-circuiteur de
 134     gestionnaire approprié. Dans l'exemple ci-dessous, toutes les
 135     requêtes pour des scripts PHP seront transmises au serveur FastCGI
 136     spécifié par mandat inverse. Cette fonctionnalité est disponible à
 137     partir de la version 2.4.10 du serveur HTTP Apache. Pour des raisons
 138     de performances, il est recommandé de définir un <a
 139     href="mod_proxy.html#workers">worker (configuration d'un
 140     mandataire)</a> représentant le même serveur fcgi:// d'arrière-plan.
 141     Avec cette configuration, il est possible d'effectuer une
 142     correspondance directe entre l'URI et le chemin du fichier sur le
 143     serveur, et le chemin local du fichier sera alors transmis au serveur
 144     d'arrière-plan. Lorsque FastCGI est configuré ainsi, le serveur est
 145     en mesure de calculer le PATH_INFO le plus approprié.
 146       </p>
 147         <example><title>Mandataire via un gestionnaire</title>
 148       <highlight language="config">
 149 &lt;FilesMatch "\.php$"&gt;
 150     # Note : la seule partie variable est /path/to/app.sock
 151     SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
 152 &lt;/FilesMatch&gt;
 153    # Définition d'une configuration de mandataire qui convient.
 154    # La partie qui est mise en correspondance avec la valeur de
 155    # SetHandler est la partie qui suit le "pipe". Si vous devez faire
 156    # une distinction, "localhost" peut être changé en un nom de serveur
 157    # unique.
 158    &lt;Proxy fcgi://localhost/ enablereuse=on max=10&gt;
 159    &lt;/Proxy&gt;
 160
 161 &lt;FilesMatch ...&gt;
 162     SetHandler  "proxy:fcgi://localhost:9000"
 163 &lt;/FilesMatch&gt;
 164
 165 &lt;FilesMatch ...&gt;
 166     SetHandler  "proxy:balancer://myappcluster/"
 167 &lt;/FilesMatch&gt;
 168       </highlight>
 169    </example>
 170 </section>
 171
 172 <section id="env"><title>Variables d'environnement</title>
 173     <p>En plus des directives de configuration qui contrôlent le
 174     comportement de <module>mod_proxy</module>, de nombreuses
 175     <dfn>variables d'environnement</dfn> permettent de piloter le
 176     fournisseur du protocole FCGI :</p>
 177     <dl>
 178         <dt>proxy-fcgi-pathinfo</dt>
 179         <dd>Par défaut, <module>mod_proxy_fcgi</module> ne créera jamais
 180         ni n'exportera la variable d'environnement <var>PATH_INFO</var>,
 181         ce qui permet au serveur FCGI d'arrière-plan de déterminer
 182         correctement <var>SCRIPT_NAME</var> et <var>Script-URI</var>, et
 183         de se conformer à la section 3.3 de la RFC 3875. Si au contraire
 184         vous avez souhaitez que <module>mod_proxy_fcgi</module> génère une
 185         "estimation la plus exacte possible" de <var>PATH_INFO</var>,
 186         définissez la variable d'environnement
 187         <var>proxy-fcgi-pathinfo</var>. Ceci peut servir de
 188         contournement pour une bogue présente dans certaines
 189         implémentations de FCGI. Cette variable peut être
 190         multivaluée afin de pouvoir choisir la valeur la plus appropriée
 191         (versions 2.4.11 et supérieures) :
 192         <dl>
 193           <dt>first-dot</dt>
 194           <dd>PATH_INFO est extrait à partir du slash qui suit le
 195           <em>premier</em> "." de l'URL.</dd>
 196           <dt>last-dot</dt>
 197           <dd>PATH_INFO est extrait à partir du slash qui suit le
 198           <em>dernier</em> "." de l'URL.</dd>
 199           <dt>full</dt>
 200           <dd>PATH_INFO est calculé en supposant que l'URL correspond au
 201           chemin du système de fichiers.</dd>
 202           <dt>unescape</dt>
 203           <dd>PATH_INFO correspond à la partie chemin de l'URL avec ses
 204           séquences d'échappement décodées.</dd>
 205           <dt>toute autre valeur</dt>
 206           <dd>PATH_INFO correspond à la partie chemin de l'URL.
 207               Auparavant, c'était la seule option pour proxy-fcgi-pathinfo.</dd>
 208          </dl>
 209         </dd>
 210     </dl>
 211 </section>
 212
 213 <directivesynopsis>
 214 <name>ProxyFCGIBackendType</name>
 215 <description>Spécifie le type de l'application FastCGI d'arrière-plan</description>
 216 <syntax>ProxyFCGIBackendType FPM|GENERIC</syntax>
 217 <default>ProxyFCGIBackendType FPM</default>
 218 <contextlist><context>server config</context>
 219 <context>virtual host</context><context>directory</context>
 220 <context>.htaccess</context></contextlist>
 221 <compatibility>Disponible à partir de la version 2.5 du serveur HTTP Apache</compatibility>
 222
 223 <usage>
 224 <p>Cette directive permet de spécifier le type de l'application FastCGI
 225 d'arrière-plan. Certains serveurs FastCGI, comme PHP-FPM, utilisent de manière
 226 historique des variables d'environnement exotiques pour identifier le type du
 227 serveur mandataire utilisé. Définissez cette directive à "GENERIC" si votre
 228 application n'est pas de type PHP-FPM et n'interpréter pas correctement des
 229 variables d'environnement comme SCRIPT_FILENAME ou PATH_TRANSLATED telles
 230 qu'elles sont définies par le serveur.</p>
 231
 232 <p>SCRIPT_FILENAME est un exemple de valeur modifiée par la définition de cette
 233 directive. Historiquement, lorsqu'on utilisait le module
 234 <module>mod_proxy_fcgi</module>, SCRIPT_FILENAME était préfixé par la chaîne
 235 "proxy:fcgi://". C'est cette variable que lisent certaines applications FastCGI
 236 génériques en tant que valeur en entrée pour leur script ; cependant, PHP-FPM
 237 peut supprimer le préfixe, puis garder en mémoire qu'il communique avec Apache.
 238 Avec les versions 2.4.21 à 2.4.25, ce préfixe était automatiquement supprimé par
 239 le serveur, empêchant ainsi PHP-FPM de détecter et interopérer avec Apache dans
 240 certains scénarios.</p>
 241 </usage>
 242 </directivesynopsis>
 243
 244 <directivesynopsis>
 245 <name>ProxyFCGISetEnvIf</name>
 246 <description>Permet d'adapter la valeur des variables envoyées aux serveurs
 247 FastCGI</description>
 248 <syntax>ProxyFCGISetEnvIf <var>conditional-expression</var>
 249     [!]<var>environment-variable-name</var>
 250     [<var>value-expression</var>]</syntax>
 251 <contextlist><context>server config</context>
 252 <context>virtual host</context><context>directory</context>
 253 <context>.htaccess</context></contextlist>
 254 <compatibility>Disponible à partir de la version 2.5 du serveur HTTP Apache.</compatibility>
 255
 256 <usage>
 257 <p>Juste avant la transmission d'une requête au serveur FastCGI configuré, le
 258 coeur du programme du serveur web définit un certain nombre de variables
 259 d'environnement en fonction de certains détails de la requête considérée. Les
 260 programmes FastCGI utilisent souvent ces variables comme données en entrée afin
 261 de déterminer quels scripts sous-jacents ils vont exécuter, ou quelles données
 262 en sortie doivent être produites.</p>
 263 <p>Voici quelques exemples de variables d'environnement importantes :</p>
 264 <ul>
 265   <li>SCRIPT_NAME</li>
 266   <li>SCRIPT_FILENAME</li>
 267   <li>REQUEST_URI</li>
 268   <li>PATH_INFO</li>
 269   <li>PATH_TRANSLATED</li>
 270 </ul>
 271
 272 <p>Cette directive permet de passer outre les variables d'environnement
 273 ci-dessus, entre autres. Elle est évaluée après la définition de la valeur
 274 initiale de ces variables ; elle peuvent donc être utilisées comme entrées dans
 275 les expressions définissants les conditions et les valeurs.</p>
 276 <p>Syntaxe des paramètres :</p>
 277 <dl>
 278 <dt>conditional-expression</dt>
 279 <dd>Définit une condition en fonction de laquelle la
 280 variable d'environnement qui suit sera modifiée ou non. Pour la syntaxe de cette
 281 expression, reportez-vous aux exemples qui suivent ou à la spécification
 282 détaillée dans le document <a href="../expr.html">ap_expr</a>.
 283    </dd>
 284 <dt>environment-variable-name</dt>
 285 <dd>Spécifie le nom de la variable d'environnement à modifier, par exemple
 286 PATH_INFO. Si elle est précédée d'un point d'exclamation, la définition de la
 287 variable sera annulée.</dd>
 288 <dt>value-expression</dt>
 289 <dd>Spécifie la nouvelle valeur de la variable "environment-variable-name". On
 290 peut inclure des
 291 références arrières, comme "$1", issues de captures en provenance de
 292 l'expression rationnelle <var>conditional-expression</var>. Si cette valeur est
 293 omise, la variable est définie (ou sa valeur est écrasée) par une chaîne vide
 294 &mdash; voir cependant la note ci-après.</dd>
 295 </dl>
 296
 297 <example>
 298    <highlight language="config">
 299 # Une modification basique, inconditionnelle
 300 ProxyFCGISetEnvIf "true" PATH_INFO "/example"
 301
 302 # Utilisation d'une variable d'environnement pour spécifier la nouvelle valeur
 303 ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"
 304 <br/>
 305 # Utilisation de captures dans la condition et de références arrières dans la
 306 # nouvelle valeur
 307 ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m#(/.*prefix)(\d+)(.*)#" PATH_TRANSLATED "$1$3"
 308    </highlight>
 309 </example>
 310
 311 <note><title>Note : Annulation définition ou valeur vide</title>
 312   La ligne suivante annule la définition de la variable <code>VARIABLE</code>,
 313   ce qui l'empêche d'être envoyée au serveur FastCGI :
 314
 315     <highlight language="config">ProxyFCGISetEnvIf true !VARIABLE</highlight>
 316
 317   La ligne suivante, quant à elle, efface la <em>valeur</em> de la variable
 318   <code>VARIABLE</code> en lui affectant la chaîne vide ; cette variable
 319   <code>VARIABLE</code> sera alors tout de même envoyée au serveur FastCGI :
 320
 321     <highlight language="config">ProxyFCGISetEnvIf true VARIABLE</highlight>
 322
 323   La spécification CGI/1.1 <a
 324   href="https://tools.ietf.org/html/rfc3875#section-4.1">ne fait pas de
 325   distinction</a> entre une variable contenant une chaîne vide et une variable qui
 326   n'existe pas. De nombreuses implémentations CGI et FastCGI font cependant
 327   cette distinction (ou permettent aux scripts de la faire). Le choix de celle
 328   que vous allez utiliser dépend de votre implémentation et de la raison qui
 329   vous pousse à modifier cette variable.
 330 </note>
 331
 332 </usage>
 333 </directivesynopsis>
 334
 335 </modulesynopsis>