docker-easy-haproxy/docs/reference/plugins/fastcgi.md

---
sidebar_position: 2
sidebar_label: "FastCGI"
---

# 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:

```yaml
# 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)

```yaml
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)

```yaml
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.

```yaml
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

```yaml
# /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

```haproxy
# 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](../../guides/plugins.md)
- [Container Labels Reference](../container-labels.md)