mod_proxy_fcgi Module fournissant le support de FastCGI à mod_proxy Extension mod_proxy_fcgi.c proxy_fcgi_module Disponible depuis la version 2.3 d'Apache

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.

 fcgistarter mod_proxy mod_authnz_fcgi
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, 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/"

Dans l'exemple suivant, on force le module à traiter les paquets de données en provenance du serveur FCGI d'arrière-plan dès leur réception, sans les faire transiter par un tampon.

Force le traitement des données FCGI sans mise en tampon ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" enablereuse=on flushpackets=on

L'exemple suivant est similaire au précédent avec une différence : ici, les données en provenance du serveur FCGI d'arrière-plan sont traitées après un temps de valeur fixe (elles sont mises en tampon). Cette méthode est utile si le serveur FCGI d'arrière-plan envoie ses données sous forme de petits paquets, auquel cas le traitement immédiat de chacun d'entre eux serait inefficace et couteux en ressources. Notez que cet exemple ne sera peut-être pas adapté dans le cas où l'envoi de paquets de données par l'application FCGI est bloqué par l'attente de données en provenance du client.

Force le traitement des données FCGI après une mise en tampon de 20ms ProxyPassMatch "^/myapp/.*\.php(/.*)?$" "fcgi://localhost:9000/var/www/" flushpackets=on flushwait=20

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.
ProxyFCGIBackendType Spécifie le type de l'application FastCGI d'arrière-plan ProxyFCGIBackendType FPM|GENERIC ProxyFCGIBackendType FPM server config virtual hostdirectory .htaccess FileInfo 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.

 ProxyFCGISetEnvIf Permet d'adapter la valeur des variables envoyées aux serveurs FastCGI ProxyFCGISetEnvIf conditional-expression [!]environment-variable-name [value-expression] server config virtual hostdirectory .htaccess FileInfo 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.