Module Apache mod_proxy_fcgi

Langues Disponibles: en | + fr

+ + + + +

Description:	Module fournissant le support de FastCGI à +`mod_proxy`
Statut:	Extension
Identificateur de Module:	proxy_fcgi_module
Fichier Source:	mod_proxy_fcgi.c
Compatibilité:	Disponible depuis la version 2.3 d'Apache

Sommaire

+ +

Pour fonctionner, ce module nécessite le chargement de + mod_proxy. Il fournit le support du protocole FastCGI.

+ +

Ainsi, pour pouvoir traiter le protocole FastCGI, + mod_proxy et mod_proxy_fcgi + doivent être chargés dans le serveur.

+ +

A la différence de mod_fcgid et mod_fastcgi, + mod_proxy_fcgi n'est pas en mesure de démarrer le + processus de l'application ; fcgistarter est + fourni à cet effet sur certaines plateformes. Le framework + applicatif FastCGI utilisé peut aussi fournir la gestion des + processus ou des lancements de programmes externes.

+ +

Avertissement

N'activez pas la fonctionnalité de mandataire avant d'avoir sécurisé votre serveur. Les + serveurs mandataires ouverts sont dangereux non seulement pour + votre réseau, mais aussi pour l'Internet au sens large.

Directives

ProxyFCGIBackendType
ProxyFCGISetEnvIf

Traitement des bugs

Voir aussi

Exemples

Pour que ces exemples fonctionnent, vous ne devez pas oublier + d'activer mod_proxy et + mod_proxy_fcgi.

+ +

Instance d'application unique

ProxyPass "/mon_appli/" "fcgi://localhost:4000/"

+ + +

mod_proxy_fcgi interdisant par défaut la + réutilisation des connexions, lorsqu'une requête a été traitée, la + connexion ne sera pas maintenue ouverte par le processus enfant + httpd, et ne sera donc pas réutilisée. Cependant, si l'application + FastCGI supporte les connexions httpd simultanées, vous pouvez opter + pour la réutilisation des connexions comme dans l'exemple suivant :

+ +

Instance d'application unique, réutilisation + des connexions (versions 2.4.11 et supérieures)

ProxyPass "/myapp/" "fcgi://localhost:4000/" enablereuse=on

+ +

Active la réutilisation des connexions vers un serveur FCGI + d'arrière-plan tel que PHP-FPM

Il faut garder à l'esprit que PHP-FPM (en février 2018) utilise un modèle + du style prefork ; autrement dit, chacun de ses processus de travail ne peut + gérer qu'une connexion à la fois.
Par défaut et lorsqu'il est + configuré avec enablereuse=on et lorsqu'un MPM à base de + threads est utilisé (comme worker ou + event), mod_proxy autorise un jeu de ThreadsPerChild connexions vers le serveur + d'arrière-plan pour chaque processus httpd, et par conséquent, il faut + prêter une attention particulière aux situations suivantes :

Avec une charge en HTTP/1, il est fort probable que le nombre de + connexions vers le serveur FCGI d'arrière-plan augmente jusqu'à atteindre + MaxRequestWorkers.
Avec une charge en HTTP/2, et vue la manière dont + mod_http2 est implémenté, il y a des threads de travail + h2 additionnels qui peuvent forcer la création de connexions + supplémentaires vers le serveur d'arrière-plan. Le nombre total de + connexions que contiennent les jeux de connexions peut alors dépasser + MaxRequestWorkers.

Le nombre maximum de processus de travail PHP-FPM doit être défini + judicieusement car il est possible qu'ils finissent par rester dans l'état + occupé ("busy") pour ne gérer que des connexions persistantes inactives, + sans avoir la possibilité d'en établir de nouvelles ; ce qui se traduira + pour l'utilisateur final par une pile de "HTTP request timeouts".

+ +

Dans l'exemple suivant, l'URI de la requête est transmis en tant + que chemin du système de fichiers pour l'exécution du démon PHP-FPM. + L'URL de la requête est implicitement ajoutée au second paramètre. + PHP-FPM est à l'écoute de l'hôte et du port qui + suivent fcgi://. La conservation/réutilisation des connexions est activée.

PHP-FPM

ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on

+ +

Dans l'exemple suivant, l'URI de la requête est transmis en tant + que chemin du système de fichiers pour l'exécution du démon PHP-FPM. + Dans ce cas cependant, PHP-FPM est à l'écoute d'un socket de domaine + unix (UDS). Cette fonctionnalité est disponible à partir de la + version 2.4.9. Avec cette syntaxe, si un nom d'hôte et un port sont + ajoutés après fcgi://, ils seront ignorés.

PHP-FPM with UDS

ProxyPassMatch "^/(.*\.php(/.*)?)$" "unix:/var/run/php5-fpm.sock|fcgi://localhost/var/www/"

+ +

La passerelle à répartition de charge nécessite le chargement du + module mod_proxy_balancer et d'au moins un module + fournissant un algorithme de répartition de charge, comme + mod_lbmethod_byrequests en plus des modules + déjà cités. mod_lbmethod_byrequests est le module + par défaut et sera utilisé dans cet exemple de configuration.

+ +

Passerelle à répartition de charge vers plusieurs + instances de l'application

ProxyPass "/myapp/" "balancer://myappcluster/"
+<Proxy "balancer://myappcluster/">
+    BalancerMember "fcgi://localhost:4000"
+    BalancerMember "fcgi://localhost:4001"
+</Proxy>

+ +

Vous pouvez aussi forcer le traitement d'une requête en tant que + requête de mandataire inverse en créant un court-circuiteur de + gestionnaire approprié. Dans l'exemple ci-dessous, toutes les + requêtes pour des scripts PHP seront transmises au serveur FastCGI + spécifié par mandat inverse. Cette fonctionnalité est disponible à + partir de la version 2.4.10 du serveur HTTP Apache. Pour des raisons + de performances, il est recommandé de définir un worker (configuration d'un + mandataire) représentant le même serveur fcgi:// d'arrière-plan. + Avec cette configuration, il est possible d'effectuer une + correspondance directe entre l'URI et le chemin du fichier sur le + serveur, et le chemin local du fichier sera alors transmis au serveur + d'arrière-plan. Lorsque FastCGI est configuré ainsi, le serveur est + en mesure de calculer le PATH_INFO le plus approprié. +

Mandataire via un gestionnaire

<FilesMatch "\.php$">
+    # Note : la seule partie variable est /path/to/app.sock
+    SetHandler  "proxy:unix:/path/to/app.sock|fcgi://localhost/"
+</FilesMatch>
+   # Définition d'une configuration de mandataire qui convient.
+   # La partie qui est mise en correspondance avec la valeur de
+   # SetHandler est la partie qui suit le "pipe". Si vous devez faire
+   # une distinction, "localhost" peut être changé en un nom de serveur
+   # unique.
+   <Proxy "fcgi://localhost/" enablereuse=on max=10>
+   </Proxy>
+
+<FilesMatch ...>
+    SetHandler  "proxy:fcgi://localhost:9000"
+</FilesMatch>
+
+<FilesMatch ...>
+    SetHandler  "proxy:balancer://myappcluster/"
+</FilesMatch>

Variables d'environnement

En plus des directives de configuration qui contrôlent le + comportement de mod_proxy, de nombreuses + variables d'environnement permettent de piloter le + fournisseur du protocole FCGI :

proxy-fcgi-pathinfo

Lorsqu'il est configuré via les directives ProxyPass ou ProxyPassMatch, + mod_proxy_fcgi ne définit + pas la variable d'environnement PATH_INFO, + ce qui permet au serveur FCGI d'arrière-plan de déterminer + correctement SCRIPT_NAME et Script-URI, et + de se conformer à la section 3.3 de la RFC 3875. Si au contraire + vous avez souhaitez que mod_proxy_fcgi génère une + "estimation la plus exacte possible" de PATH_INFO, + définissez la variable d'environnement + proxy-fcgi-pathinfo. Ceci peut servir de + contournement pour une bogue présente dans certaines + implémentations de FCGI. Cette variable peut être + multivaluée afin de pouvoir choisir la valeur la plus appropriée + (versions 2.4.11 et supérieures) : +

first-dot: PATH_INFO est extrait à partir du slash qui suit le + premier "." de l'URL.
last-dot: PATH_INFO est extrait à partir du slash qui suit le + dernier "." de l'URL.
full: PATH_INFO est calculé en supposant que l'URL correspond au + chemin du système de fichiers.
unescape: PATH_INFO correspond à la partie chemin de l'URL avec ses + séquences d'échappement décodées.
toute autre valeur: PATH_INFO correspond à la partie chemin de l'URL. + Auparavant, c'était la seule option pour proxy-fcgi-pathinfo.

Directive ProxyFCGIBackendType

+ + + + + + + + +

Description:	Spécifie le type de l'application FastCGI d'arrière-plan
Syntaxe:	`ProxyFCGIBackendType FPM\|GENERIC`
Défaut:	`ProxyFCGIBackendType FPM`
Contexte:	configuration globale, serveur virtuel, répertoire, .htaccess
Statut:	Extension
Module:	mod_proxy_fcgi
Compatibilité:	Disponible à partir de la version 2.4.26 du serveur HTTP Apache

Cette directive permet de spécifier le type de l'application FastCGI +d'arrière-plan. Certains serveurs FastCGI, comme PHP-FPM, utilisent de manière +historique des variables d'environnement exotiques pour identifier le type du +serveur mandataire utilisé. Définissez cette directive à "GENERIC" si votre +application n'est pas de type PHP-FPM et n'interpréter pas correctement des +variables d'environnement comme SCRIPT_FILENAME ou PATH_TRANSLATED telles +qu'elles sont définies par le serveur.

+ +

SCRIPT_FILENAME est un exemple de valeur modifiée par la définition de cette +directive. Historiquement, lorsqu'on utilisait le module +mod_proxy_fcgi, SCRIPT_FILENAME était préfixé par la chaîne +"proxy:fcgi://". C'est cette variable que lisent certaines applications FastCGI +génériques en tant que valeur en entrée pour leur script ; cependant, PHP-FPM +peut supprimer le préfixe, puis garder en mémoire qu'il communique avec Apache. +Avec les versions 2.4.21 à 2.4.25, ce préfixe était automatiquement supprimé par +le serveur, empêchant ainsi PHP-FPM de détecter et interopérer avec Apache dans +certains scénarios.

+ +

Directive ProxyFCGISetEnvIf

+ + + + + + + +

Description:	Permet d'adapter la valeur des variables envoyées aux serveurs +FastCGI
Syntaxe:	`ProxyFCGISetEnvIf conditional-expression + [!]environment-variable-name + [value-expression]`
Contexte:	configuration globale, serveur virtuel, répertoire, .htaccess
Statut:	Extension
Module:	mod_proxy_fcgi
Compatibilité:	Disponible à partir de la version 2.4.26 du serveur HTTP Apache.

Juste avant la transmission d'une requête au serveur FastCGI configuré, le +coeur du programme du serveur web définit un certain nombre de variables +d'environnement en fonction de certains détails de la requête considérée. Les +programmes FastCGI utilisent souvent ces variables comme données en entrée afin +de déterminer quels scripts sous-jacents ils vont exécuter, ou quelles données +en sortie doivent être produites.

Voici quelques exemples de variables d'environnement importantes :

SCRIPT_NAME
SCRIPT_FILENAME
REQUEST_URI
PATH_INFO
PATH_TRANSLATED

+ +

Cette directive permet de passer outre les variables d'environnement +ci-dessus, entre autres. Elle est évaluée après la définition de la valeur +initiale de ces variables ; elle peuvent donc être utilisées comme entrées dans +les expressions définissants les conditions et les valeurs.

Syntaxe des paramètres :

conditional-expression: Définit une condition en fonction de laquelle la +variable d'environnement qui suit sera modifiée ou non. Pour la syntaxe de cette +expression, reportez-vous aux exemples qui suivent ou à la spécification +détaillée dans le document ap_expr. +
environment-variable-name: Spécifie le nom de la variable d'environnement à modifier, par exemple +PATH_INFO. Si elle est précédée d'un point d'exclamation, la définition de la +variable sera annulée.
value-expression: Spécifie la nouvelle valeur de la variable "environment-variable-name". On +peut inclure des +références arrières, comme "$1", issues de captures en provenance de +l'expression rationnelle conditional-expression. Si cette valeur est +omise, la variable est définie (ou sa valeur est écrasée) par une chaîne vide +— voir cependant la note ci-après.

+ +

# Une modification basique, inconditionnelle
+ProxyFCGISetEnvIf "true" PATH_INFO "/example"
+
+# Utilisation d'une variable d'environnement pour spécifier la nouvelle valeur
+ProxyFCGISetEnvIf "true" PATH_INFO "%{reqenv:SCRIPT_NAME}"
+

+# Utilisation de captures dans la condition et de références arrières dans la
+# nouvelle valeur
+ProxyFCGISetEnvIf "reqenv('PATH_TRANSLATED') =~ m#(/.*prefix)(\d+)(.*)#" PATH_TRANSLATED "$1$3"

+ +

Note : Annulation définition ou valeur vide

+ La ligne suivante annule la définition de la variable VARIABLE, + ce qui l'empêche d'être envoyée au serveur FastCGI : + +

ProxyFCGISetEnvIf true !VARIABLE

+ + + La ligne suivante, quant à elle, efface la valeur de la variable + VARIABLE en lui affectant la chaîne vide ; cette variable + VARIABLE sera alors tout de même envoyée au serveur FastCGI : + +

ProxyFCGISetEnvIf true VARIABLE

+ + + La spécification CGI/1.1 ne fait pas de + distinction entre une variable contenant une chaîne vide et une variable qui + n'existe pas. De nombreuses implémentations CGI et FastCGI font cependant + cette distinction (ou permettent aux scripts de la faire). Le choix de celle + que vous allez utiliser dépend de votre implémentation et de la raison qui + vous pousse à modifier cette variable. +