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

Option	Description	Default
enabled	Enable/disable plugin	true
document_root	Document root path	/var/www/html
script_filename	Custom pattern for SCRIPT_FILENAME	%[path] (uses HAProxy's default)
index_file	Default index file	index.php
path_info	PATH_INFO preset or custom regex	php
log_stderr	Forward FastCGI stderr to HAProxy logs	false
keep_conn	Reuse FastCGI connections between requests	true
custom_params	Dictionary of custom FastCGI parameters	(optional)
pass_headers	HTTP headers to forward to the FastCGI app	(optional)

path_info — PATH_INFO Presets

The path_info option accepts a preset name or a custom regex. Built-in presets:

Preset	Language	Regex
php	PHP (default)	^(/.+\.php)(/.*)?$
python	Python FastCGI	^(/.+\.py)(/.*)?$
perl	Perl/CGI	^(/.+\.(pl|cgi))(/.*)?$
ruby	Ruby FastCGI	^(/.+\.rb)(/.*)?$
any	Generic	^(.+?)(/.*)?$

Pass false to disable PATH_INFO entirely, or any other string to use it as a custom regex directly.

Setting path_info: true maps to php for backward compatibility.

pass_headers — Forwarding HTTP Headers

important

HAProxy strips Authorization, Proxy-Authorization, and all hop-by-hop headers before forwarding requests to the FastCGI backend. Applications that rely on these headers (e.g. APIs using Bearer tokens, Basic auth, or JWT) will fail silently without this option.

pass_headers accepts a comma-separated string or a list of strings/dicts:

# Simple — single header
pass_headers: "Authorization"

# Multiple — comma-separated
pass_headers: "Authorization, Proxy-Authorization"

# With ACL condition — list of dicts
pass_headers:
  - Authorization
  - name: X-Custom-Header
    condition: "if { ssl_fc }"

Note: Content-Type and Content-Length cannot be passed here — they are automatically converted to the CGI parameters CONTENT_TYPE and CONTENT_LENGTH.

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

Kubernetes Annotations

The proto: fcgi backend protocol is set automatically when using this plugin — no need to add easyhaproxy.proto manually.

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"
    easyhaproxy.plugin.fastcgi.script_filename: "/var/www/html/index.php"
    easyhaproxy.plugin.fastcgi.pass_headers: "Authorization, Proxy-Authorization"
spec:
  ingressClassName: easyhaproxy
  rules:
    - host: phpapp.example.com
      http:
        paths:
          - path: /
            pathType: ImplementationSpecific
            backend:
              service:
                name: php-fpm
                port:
                  number: 9000

Static YAML Configuration

# /etc/easyhaproxy/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

Environment Variable	Config Key	Type	Default	Description
EASYHAPROXY_PLUGIN_FASTCGI_ENABLED	enabled	boolean	true	Enable/disable plugin for all domains
EASYHAPROXY_PLUGIN_FASTCGI_DOCUMENT_ROOT	document_root	string	/var/www/html	Document root path
EASYHAPROXY_PLUGIN_FASTCGI_SCRIPT_FILENAME	script_filename	string	%[path]	Custom pattern for SCRIPT_FILENAME
EASYHAPROXY_PLUGIN_FASTCGI_INDEX_FILE	index_file	string	index.php	Default index file
EASYHAPROXY_PLUGIN_FASTCGI_PATH_INFO	path_info	boolean	true	Enable PATH_INFO support

Generated HAProxy Configuration

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

# Backend configuration (added to the backend section)
backend srv_phpapp_local_80
    use-fcgi-app fcgi_phpapp_local
    server srv-0 172.19.0.3:9000 proto fcgi

CGI Parameters

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

Related Documentation

• Plugin System Overview
• Container Labels Reference