Skip to main content

FastCGI Plugin

Type: Domain Plugin Runs: Once for each discovered domain/host

Overview​

The FastCGI plugin configures HAProxy to communicate with PHP-FPM and other FastCGI applications. It automatically generates the necessary HAProxy fcgi-app configuration that defines CGI parameters for proper PHP-FPM communication.

Why Use It​

Automatically generates HAProxy fcgi-app configuration that defines required CGI parameters for PHP-FPM communication without manual HAProxy configuration.

Configuration Options​

OptionDescriptionDefault
enabledEnable/disable plugintrue
document_rootDocument root path/var/www/html
script_filenameCustom pattern for SCRIPT_FILENAME%[path] (uses HAProxy's default)
index_fileDefault index fileindex.php
path_infoEnable PATH_INFO supporttrue
custom_paramsDictionary of custom FastCGI parameters(optional)

Configuration Examples​

Docker/Docker Compose (TCP connection)​

services:
  php-fpm:
    image: php:8.2-fpm
    labels:
      easyhaproxy.http.host: phpapp.local
      easyhaproxy.http.port: 80
      easyhaproxy.http.localport: 9000
      easyhaproxy.http.proto: fcgi
      easyhaproxy.http.plugins: fastcgi
      easyhaproxy.http.plugin.fastcgi.document_root: /var/www/html
      easyhaproxy.http.plugin.fastcgi.index_file: index.php
    volumes:
      - ./app:/var/www/html

Docker/Docker Compose (Unix socket)​

services:
  php-fpm:
    image: php:8.2-fpm
    labels:
      easyhaproxy.http.host: phpapp.local
      easyhaproxy.http.socket: /run/php/php-fpm.sock
      easyhaproxy.http.proto: fcgi
      easyhaproxy.http.plugins: fastcgi
      easyhaproxy.http.plugin.fastcgi.document_root: /var/www/html
      easyhaproxy.http.plugin.fastcgi.index_file: index.php
    volumes:
      - ./app:/var/www/html
      - /run/php:/run/php

Custom Document Root and Index File​

labels:
  easyhaproxy.http.plugins: fastcgi
  easyhaproxy.http.plugin.fastcgi.document_root: /var/www/myapp/public
  easyhaproxy.http.plugin.fastcgi.index_file: app.php
  easyhaproxy.http.plugin.fastcgi.path_info: true

Kubernetes Annotations​

apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
  annotations:
    easyhaproxy.plugins: "fastcgi"
    easyhaproxy.plugin.fastcgi.document_root: "/var/www/html"
    easyhaproxy.plugin.fastcgi.index_file: "index.php"
spec:
  rules:
    - host: phpapp.example.com
      http:
        paths:
          - path: /
            backend:
              service:
                name: php-fpm
                port:
                  number: 9000

Static YAML Configuration​

# /etc/haproxy/static/config.yaml
easymapping:
  - host: phpapp.local
    port: 80
    container: php-fpm:9000
    proto: fcgi
    plugins:
      - fastcgi
    plugin_config:
      fastcgi:
        document_root: /var/www/html
        index_file: index.php
        path_info: true

Environment Variables​

Configure FastCGI plugin defaults for all domains:

Environment VariableConfig KeyTypeDefaultDescription
EASYHAPROXY_PLUGIN_FASTCGI_ENABLEDenabledbooleantrueEnable/disable plugin for all domains
EASYHAPROXY_PLUGIN_FASTCGI_DOCUMENT_ROOTdocument_rootstring/var/www/htmlDocument root path
EASYHAPROXY_PLUGIN_FASTCGI_SCRIPT_FILENAMEscript_filenamestring%[path]Custom pattern for SCRIPT_FILENAME
EASYHAPROXY_PLUGIN_FASTCGI_INDEX_FILEindex_filestringindex.phpDefault index file
EASYHAPROXY_PLUGIN_FASTCGI_PATH_INFOpath_infobooleantrueEnable PATH_INFO support

Note: Environment variables set defaults for ALL domains. To configure per-domain, use container labels or Kubernetes annotations. Custom params (custom_params) cannot be configured via environment variables - use YAML or labels instead.

Generated HAProxy Configuration​

The plugin generates a top-level fcgi-app section and a use-fcgi-app directive in the backend:

# Top-level fcgi-app definition (added after defaults, before frontends/backends)
fcgi-app fcgi_phpapp_local
    docroot /var/www/html
    index index.php
    path-info ^(/.+\.php)(/.*)?$

# Backend configuration (added to the backend section)
backend srv_phpapp_local_80
    use-fcgi-app fcgi_phpapp_local
    # TCP connection:
    server srv-0 172.19.0.3:9000 proto fcgi
    # OR Unix socket:
    # server srv-0 /run/php/php-fpm.sock proto fcgi

CGI Parameters​

Note: HAProxy automatically sets standard CGI parameters based on the fcgi-app configuration when communicating with PHP-FPM via the FastCGI protocol.

The plugin configures:

  • ✅ SCRIPT_FILENAME - Path to PHP script
  • ✅ DOCUMENT_ROOT - Document root directory
  • ✅ SCRIPT_NAME - Script name from URL
  • ✅ REQUEST_URI - Full request URI with query string
  • ✅ QUERY_STRING - URL query parameters
  • ✅ REQUEST_METHOD - HTTP method (GET, POST, etc.)
  • ✅ CONTENT_TYPE & CONTENT_LENGTH - Request body info
  • ✅ SERVER_NAME & SERVER_PORT - Server details
  • ✅ HTTPS - SSL/TLS status
  • ✅ PATH_INFO - Path information (optional)

Important Notes​

  • Required: Use this plugin together with proto: fcgi parameter for complete PHP-FPM support
  • The plugin runs once per domain during the discovery cycle
  • HAProxy handles the actual FastCGI protocol communication and CGI parameter transmission