10. Applications FastCGI

HAProxy est capable d’envoyer des requêtes HTTP vers des applications FastCGI Responder. Cette fonctionnalité a été ajoutée à HAProxy 2.1. Pour cela, les serveurs doivent être configurés pour utiliser le protocole FastCGI (en utilisant le mot-clé « proto fcgi » dans la ligne du serveur) et une application FastCGI doit être configurée et utilisée par le backend gérant ces serveurs (en utilisant le mot-clé « use-fcgi-app » dans la section proxy). Plusieurs applications FastCGI peuvent être définies, mais un seul peut être utilisé à la fois par un backend.

HAProxy implémente toutes les fonctionnalités de la spécification FastCGI pour les applications Répondre. En particulier, il est capable de multiplexer plusieurs requêtes sur une connexion simple.

10.1. Configuration

10.1.1. Section fcgi-app

fcgi-app <name>

fcgi-app <name>

Déclare une application FastCGI nommée <name>. Pour être valide, au moins le répertoire racine du document doit être défini.

acl <aclname> <criterion> [flags] [operator] <value> ...

acl <aclname> <criterion> [flags] [operator] <value> ...

Déclarer ou compléter une liste d’accès.

Voir le mot-clé « acl » dans la section 4.2 et la section 7 pour plus de détails sur l’utilisation des ACL. Les ACL définies pour une application FastCGI sont privées. Elles ne peuvent pas être utilisées par toute autre application ou par tout proxy. De la même manière, les ACL définies dans toute autre section ne sont pas utilisables par une application FastCGI. Toutefois, des ACL prédéfinies sont disponibles.

docroot <path>

docroot <path>

Définir la racine des documents sur l’hôte distant. <path> sera utilisé pour construire la valeur par défaut des paramètres FastCGI SCRIPT_FILENAME et PATH_TRANSLATED. Il s’agit d’un paramètre obligatoire.

index <script-name>

index <script-name>

Définir le nom du script qui sera ajouté après une URI se terminant par une barre oblique ("/") pour définir la valeur par défaut du paramètre FastCGI SCRIPT_NAME. Il s’agit d’un paramètre facultatif.

Exemple :

index index.php

log-stderr global

log-stderr global
log-stderr <target> [len <length>] [format <format>]
    [sample <ranges>:<sample_size>] <facility> [<level> [<minlevel>]]

Activez la journalisation des messages STDERR émis par l’application FastCGI.

Voir le mot-clé « log » dans la section 4.2 pour plus de détails. Il s’agit d’un paramètre facultatif. Par défaut, les messages STDERR sont ignorés.

pass-header <name> [ { if | unless } <condition> ]

pass-header <name> [ { if | unless } <condition> ]

Spécifiez le nom d’un en-tête de requête qui sera transmis à l’application FastCGI. Il peut éventuellement être suivi d’une condition basée sur une ACL, auquel cas il ne sera évalué que si la condition est vraie.

La plupart des en-têtes de requête sont déjà accessibles à l’application FastCGI, préfixés par “HTTP_”. Ce directive n’est donc nécessaire que pour transmettre les en-têtes qui sont volontairement omis. Actuellement, les en-têtes « Authorization », « Proxy-Authorization » et les en-têtes hop-by-hop sont omis.

Notez que les en-têtes « Content-type » et « Content-length » ne sont jamais transmis à l’application FastCGI, car ils sont déjà convertis en paramètres.

path-info <regex>

path-info <regex>

Définir une expression régulière pour extraire le nom du script et le chemin d’information à partir du chemin décodé URL. Ainsi, <regex> peut avoir deux captures : la première pour capturer le nom du script et la deuxième pour capturer le chemin d’information. La première est obligatoire, la deuxième est facultative. Cette approche permet d’extraire le nom du script à partir du chemin en ignorant le chemin d’information. Il s’agit d’un paramètre facultatif. Si ce paramètre n’est pas défini, aucune correspondance n’est effectuée sur le chemin, et les paramètres FastCGI PATH_INFO et PATH_TRANSLATED ne sont pas renseignés.

Pour des raisons de sécurité, lorsque cette expression régulière est définie, les caractères de saut de ligne et de caractère nul sont interdits dans le chemin, une fois décodé en URL. La raison de cette limitation est que, faute de quoi, la correspondance échouerait toujours (en raison d’une limitation dans la manière dont les expressions régulières sont exécutées dans HAProxy). Ainsi, si l’un de ces deux caractères est détecté dans le chemin décodé en URL, une erreur est renvoyée au client. Le principe de moindre étonnement s’applique ici.

Exemple :

path-info ^(/.+\.php)(/.*)?$ # both script-name and path-info may be set
path-info ^(/.+\.php)        # the path-info is ignored

option get-values

option get-values
no option get-values

Active ou désactive la récupération des variables relatives à la gestion des connexions.

HAProxy est capable d’envoyer le champ FCGI_GET_VALUES à l’établissement de la connexion afin de récupérer la valeur des variables suivantes :

* FCGI_MAX_REQS     Nombre maximal de requêtes simultanées que cette application acceptera.

* FCGI_MPXS_CONNS   « 0 » si cette application ne multiplexe pas les connexions,
                    « 1 » dans le cas contraire.

Certains applications FastCGI ne prennent pas en charge cette fonctionnalité. D’autres ferment la connexion immédiatement après avoir envoyé leur réponse. Par conséquent, cette option est désactivée par défaut.

Notez que le nombre maximal de requêtes simultanées acceptées par une application FastCGI est une variable de connexion. Elle limite uniquement le nombre de flux par connexion. Si la charge globale doit être limitée sur l’application, les paramètres serveur « maxconn » et « pool-max-conn » doivent être configurés. En outre, si une application ne prend pas en charge la multiplexion de connexions, le nombre maximal de requêtes simultanées est automatiquement fixé à 1.

option keep-conn

option keep-conn
no option keep-conn

Indiquez à l’application FastCGI de maintenir la connexion ouverte ou non après l’envoi d’une réponse.

Si désactivé, l’application FastCGI ferme la connexion après avoir répondu à cette requête. Par défaut, cette option est activée.

option max-reqs <reqs>

option max-reqs <reqs>

Définir le nombre maximum de requêtes simultanées que cette application acceptera.

Cette option peut être remplacée si la variable FCGI_MAX_REQS est récupérée lors de l’établissement de la connexion. En outre, si l’application ne prend pas en charge le multiplexage des connexions, cette option sera ignorée. Valeur par défaut : 1.

option mpxs-conns

option mpxs-conns
no option mpxs-conns

Active ou désactive la prise en charge du multiplexage de connexions.

Cette option peut être remplacée si la variable FCGI_MPXS_CONNS est récupérée lors de l’établissement de la connexion. Elle est désactivée par défaut.

set-param <name> <fmt> [ { if | unless } <condition> ]

set-param <name> <fmt> [ { if | unless } <condition> ]

Définissez un paramètre FastCGI qui doit être transmis à cette application. Sa valeur, définie par <fmt>, doit respecter les règles du format de journalisation personnalisé (voir la section 8.2.6 « Format de journalisation personnalisé »). Elle peut éventuellement être suivie d’une condition basée sur une ACL, auquel cas elle ne sera évaluée que si la condition est vraie.

Avec cette directive, il est possible de remplacer la valeur des paramètres FastCGI par défaut. Si la valeur est évaluée à une chaîne vide, la règle est ignorée. Ces directives sont évaluées dans l’ordre de leur déclaration.

Exemple :

# PHP only, required if PHP was built with --enable-force-cgi-redirect
set-param REDIRECT_STATUS 200

set-param PHP_AUTH_DIGEST %[req.hdr(Authorization)]

10.1.2. Section proxy

use-fcgi-app <name> Définir l’application FastCGI à utiliser pour le backend.

Arguments :

<name>    is the name of the FastCGI application to use.

Ce mot-clé n’est disponible que pour les proxies HTTP disposant de la capacité backend et comportant au moins un serveur FastCGI. Toutefois, les serveurs FastCGI peuvent être combinés avec des serveurs HTTP. Toutefois, sauf si une bonne raison s’impose, cette configuration n’est pas recommandée (voir section 10.3 pour les détails sur les limitations). Une seule application peut être définie à la fois par backend.

Notez qu’une fois une application FastCGI référencée pour un backend, selon la configuration, un traitement peut être effectué même si la requête n’est pas envoyée à un serveur FastCGI. Les règles permettant de définir des paramètres ou de transmettre des en-têtes à une application sont évaluées.

10.1.3. Exemple

frontend front-http mode http bind *:80 bind *:

  use_backend back-dynamic if { path_reg ^/.+\.php(/.*)?$ }
  default_backend back-static

backend back-static mode http server www A.B.C.D:80

backend back-dynamic mode http use-fcgi-app php-fpm server php-fpm A.B.C.D:9000 proto fcgi

fcgi-app php-fpm log-stderr global option keep-conn

  docroot /var/www/my-app
  index index.php
  path-info ^(/.+\.php)(/.*)?$

10.2. Paramètres par défaut

Un application Répondant FastCGI a le même objectif qu’un programme CGI/1.1. Selon la spécification CGI/1.1 (RFC3875), plusieurs variables doivent être transmises au script. HAProxy les définit donc, ainsi que d’autres variables couramment utilisées par les applications FastCGI. Toutes ces variables peuvent être surchargées, avec prudence toutefois.

  +-------------------+-----------------------------------------------------+
  | AUTH_TYPE         | Identifies the mechanism, if any, used by HAProxy   |
  |                   | to authenticate the user. Concretely, only the      |
  |                   | BASIC authentication mechanism is supported.        |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | CONTENT_LENGTH    | Contains the size of the message-body attached to   |
  |                   | the request. It means only requests with a known    |
  |                   | size are considered as valid and sent to the        |
  |                   | application.                                        |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | CONTENT_TYPE      | Contains the type of the message-body attached to   |
  |                   | the request. It may not be set.                     |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | DOCUMENT_ROOT     | Contains the document root on the remote host under |
  |                   | which the script should be executed, as defined in  |
  |                   | the application's configuration.                    |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | GATEWAY_INTERFACE | Contains the dialect of CGI being used by HAProxy   |
  |                   | to communicate with the FastCGI application.        |
  |                   | Concretely, it is set to "CGI/1.1".                 |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | PATH_INFO         | Contains the portion of the URI path hierarchy      |
  |                   | following the part that identifies the script       |
  |                   | itself. To be set, the directive "path-info" must   |
  |                   | be defined.                                         |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | PATH_TRANSLATED   | If PATH_INFO is set, it is its translated version.  |
  |                   | It is the concatenation of DOCUMENT_ROOT and        |
  |                   | PATH_INFO. If PATH_INFO is not set, this parameters |
  |                   | is not set too.                                     |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | QUERY_STRING      | Contains the request's query string. It may not be  |
  |                   | set.                                                |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REMOTE_ADDR       | Contains the network address of the client sending  |
  |                   | the request.                                        |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REMOTE_USER       | Contains the user identification string supplied by |
  |                   | client as part of user authentication.              |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REQUEST_METHOD    | Contains the method which should be used by the     |
  |                   | script to process the request.                      |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | REQUEST_URI       | Contains the request's URI.                         |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SCRIPT_FILENAME   | Contains the absolute pathname of the script. it is |
  |                   | the concatenation of DOCUMENT_ROOT and SCRIPT_NAME. |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SCRIPT_NAME       | Contains the name of the script. If the directive   |
  |                   | "path-info" is defined, it is the first part of the |
  |                   | URI path hierarchy, ending with the script name.    |
  |                   | Otherwise, it is the entire URI path.               |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_NAME       | Contains the name of the server host to which the   |
  |                   | client request is directed. It is the value of the  |
  |                   | header "Host", if defined. Otherwise, the           |
  |                   | destination address of the connection on the client |
  |                   | side.                                               |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_PORT       | Contains the destination TCP port of the connection |
  |                   | on the client side, which is the port the client    |
  |                   | connected to.                                       |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_PROTOCOL   | Contains the request's protocol.                    |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | SERVER_SOFTWARE   | Contains the string "HAProxy" followed by the       |
  |                   | current HAProxy version.                            |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+
  | HTTPS             | Set to a non-empty value ("on") if the script was   |
  |                   | queried through the HTTPS protocol.                 |
  |                   |                                                     |
  +-------------------+-----------------------------------------------------+

10.3. Limitations

L’implémentation actuelle présente certaines limitations. La première concerne la manière dont certains en-têtes de requête sont masqués aux applications FastCGI. Ce masquage a lieu lors de l’analyse des en-têtes, du côté du backend, avant l’établissement de la connexion. À ce stade, HAProxy sait que le backend utilise une application FastCGI, mais il ne sait pas si la requête sera acheminée vers un serveur FastCGI ou non. Pour masquer les en-têtes de requête, il les supprime simplement du message HTX. Ainsi, si la requête est finalement acheminée vers un serveur HTTP, elle ne les voit jamais. Pour cette raison, il est déconseillé de mixer des serveurs FastCGI et des serveurs HTTP sous le même backend.

De même, les règles « set-param » et « pass-header » sont évaluées lors de l’analyse des en-têtes de requête. L’évaluation est donc toujours effectuée, même si la requête est finalement acheminée vers un serveur HTTP.

À propos des règles « set-param », lorsqu’une règle est appliquée, un en-tête pseudo est ajouté au message HTX. Ainsi, de la même manière que pour les réécritures d’en-têtes HTTP, cela peut échouer si la mémoire tampon est pleine. Les règles « set-param » peuvent entrer en concurrence avec les règles « http-request ».

Enfin, tous les paramètres FastCGI et les en-têtes HTTP sont envoyés dans un enregistrement unique FCGI_PARAM. Le codage de cet enregistrement doit être effectué en une seule passe, faute de quoi une erreur de traitement est renvoyée. Cela signifie que l’enregistrement FCGI_PARAM, une fois encodé, ne doit pas dépasser la taille d’un tampon. Toutefois, aucune réserve n’est à respecter ici.