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: 1793934 -->
   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 <override>FileInfo</override>
 222 <compatibility>Disponible à partir de la version 2.4.26 du serveur HTTP Apache</compatibility>
 223
 224 <usage>
 225 <p>Cette directive permet de spécifier le type de l'application FastCGI
 226 d'arrière-plan. Certains serveurs FastCGI, comme PHP-FPM, utilisent de manière
 227 historique des variables d'environnement exotiques pour identifier le type du
 228 serveur mandataire utilisé. Définissez cette directive à "GENERIC" si votre
 229 application n'est pas de type PHP-FPM et n'interpréter pas correctement des
 230 variables d'environnement comme SCRIPT_FILENAME ou PATH_TRANSLATED telles
 231 qu'elles sont définies par le serveur.</p>
 232
 233 <p>SCRIPT_FILENAME est un exemple de valeur modifiée par la définition de cette
 234 directive. Historiquement, lorsqu'on utilisait le module
 235 <module>mod_proxy_fcgi</module>, SCRIPT_FILENAME était préfixé par la chaîne
 236 "proxy:fcgi://". C'est cette variable que lisent certaines applications FastCGI
 237 génériques en tant que valeur en entrée pour leur script ; cependant, PHP-FPM
 238 peut supprimer le préfixe, puis garder en mémoire qu'il communique avec Apache.
 239 Avec les versions 2.4.21 à 2.4.25, ce préfixe était automatiquement supprimé par
 240 le serveur, empêchant ainsi PHP-FPM de détecter et interopérer avec Apache dans
 241 certains scénarios.</p>
 242 </usage>
 243 </directivesynopsis>
 244
 245 <directivesynopsis>
 246 <name>ProxyFCGISetEnvIf</name>
 247 <description>Permet d'adapter la valeur des variables envoyées aux serveurs
 248 FastCGI</description>
 249 <syntax>ProxyFCGISetEnvIf <var>conditional-expression</var>
 250     [!]<var>environment-variable-name</var>
 251     [<var>value-expression</var>]</syntax>
 252 <contextlist><context>server config</context>
 253 <context>virtual host</context><context>directory</context>
 254 <context>.htaccess</context></contextlist>
 255 <override>FileInfo</override>
 256 <compatibility>Disponible à partir de la version 2.4.26 du serveur HTTP Apache.</compatibility>
 257
 258 <usage>
 259 <p>Juste avant la transmission d'une requête au serveur FastCGI configuré, le
 260 coeur du programme du serveur web définit un certain nombre de variables
 261 d'environnement en fonction de certains détails de la requête considérée. Les
 262 programmes FastCGI utilisent souvent ces variables comme données en entrée afin
 263 de déterminer quels scripts sous-jacents ils vont exécuter, ou quelles données
 264 en sortie doivent être produites.</p>
 265 <p>Voici quelques exemples de variables d'environnement importantes :</p>
 266 <ul>
 267   <li>SCRIPT_NAME</li>
 268   <li>SCRIPT_FILENAME</li>
 269   <li>REQUEST_URI</li>
 270   <li>PATH_INFO</li>
 271   <li>PATH_TRANSLATED</li>
 272 </ul>
 273
 274 <p>Cette directive permet de passer outre les variables d'environnement
 275 ci-dessus, entre autres. Elle est évaluée après la définition de la valeur
 276 initiale de ces variables ; elle peuvent donc être utilisées comme entrées dans
 277 les expressions définissants les conditions et les valeurs.</p>
 278 <p>Syntaxe des paramètres :</p>
 279 <dl>
 280 <dt>conditional-expression</dt>
 281 <dd>Définit une condition en fonction de laquelle la
 282 variable d'environnement qui suit sera modifiée ou non. Pour la syntaxe de cette
 283 expression, reportez-vous aux exemples qui suivent ou à la spécification
 284 détaillée dans le document <a href="../expr.html">ap_expr</a>.
 285    </dd>
 286 <dt>environment-variable-name</dt>
 287 <dd>Spécifie le nom de la variable d'environnement à modifier, par exemple
 288 PATH_INFO. Si elle est précédée d'un point d'exclamation, la définition de la
 289 variable sera annulée.</dd>
 290 <dt>value-expression</dt>
 291 <dd>Spécifie la nouvelle valeur de la variable "environment-variable-name". On
 292 peut inclure des
 293 références arrières, comme "$1", issues de captures en provenance de
 294 l'expression rationnelle <var>conditional-expression</var>. Si cette valeur est
 295 omise, la variable est définie (ou sa valeur est écrasée) par une chaîne vide
 296 &mdash; voir cependant la note ci-après.</dd>
 297 </dl>
 298
 299 <example>
 300    <highlight language="config">
 301 # Une modification basique, inconditionnelle
 302 ProxyFCGISetEnvIf "true" PATH_INFO "/example"
 303
 304 # Utilisation d'une variable d'environnement pour spécifier la nouvelle valeur
 305 ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"
 306 <br/>
 307 # Utilisation de captures dans la condition et de références arrières dans la
 308 # nouvelle valeur
 309 ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m#(/.*prefix)(\d+)(.*)#" PATH_TRANSLATED "$1$3"
 310    </highlight>
 311 </example>
 312
 313 <note><title>Note : Annulation définition ou valeur vide</title>
 314   La ligne suivante annule la définition de la variable <code>VARIABLE</code>,
 315   ce qui l'empêche d'être envoyée au serveur FastCGI :
 316
 317     <highlight language="config">ProxyFCGISetEnvIf true !VARIABLE</highlight>
 318
 319   La ligne suivante, quant à elle, efface la <em>valeur</em> de la variable
 320   <code>VARIABLE</code> en lui affectant la chaîne vide ; cette variable
 321   <code>VARIABLE</code> sera alors tout de même envoyée au serveur FastCGI :
 322
 323     <highlight language="config">ProxyFCGISetEnvIf true VARIABLE</highlight>
 324
 325   La spécification CGI/1.1 <a
 326   href="https://tools.ietf.org/html/rfc3875#section-4.1">ne fait pas de
 327   distinction</a> entre une variable contenant une chaîne vide et une variable qui
 328   n'existe pas. De nombreuses implémentations CGI et FastCGI font cependant
 329   cette distinction (ou permettent aux scripts de la faire). Le choix de celle
 330   que vous allez utiliser dépend de votre implémentation et de la raison qui
 331   vous pousse à modifier cette variable.
 332 </note>
 333
 334 </usage>
 335 </directivesynopsis>
 336
 337 </modulesynopsis>