Configuration: FastCGI support

This page documents the fcgi directive for configuring Ferron’s FastCGI support. FastCGI enables dynamic content by forwarding requests to external application servers over TCP or Unix sockets, with support for connection pooling and keepalive for improved performance.

fcgi

example.com {
    fcgi {
        backend tcp://127.0.0.1:4000
        environment "APP_ENV" "production"
    }
}

The fcgi directive enables FastCGI protocol support. It can be written as a boolean flag to enable with defaults, with a backend URL to set the target, or as a block with nested directives to customize behavior.

backend

Configuration example:

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
    }
}

Configuration example with Unix socket:

example.com {
    fcgi {
        backend unix:///run/php/php8.4-fpm.sock
    }
}

extension

Configuration example:

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        extension ".php"
        extension ".php5" ".php7"
    }
}

environment

Configuration example:

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        environment "APP_ENV" "production"
        environment "APP_SECRET" "{{env.APP_SECRET}}"
        environment "RUBY_VERSION" "3.3"
    }
}

pass

Configuration example:

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        pass false
        extension ".php"
    }
}

keepalive

Configuration example:

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        keepalive
    }
}

fcgi_php

example.com {
    fcgi_php "unix:///run/php/php8.4-fpm.sock"
}

The fcgi_php directive is a convenience alias for PHP FastCGI backends. It enables FastCGI and automatically registers the .php file extension. This is the recommended way to host PHP applications with PHP-FPM.

Configuration example with TCP:

example.com {
    root /var/www/html
    fcgi_php "tcp://127.0.0.1:9000"
}

Configuration example with Unix socket:

example.com {
    root /var/www/html
    fcgi_php "unix:///run/php/php8.4-fpm.sock"
}

Connection pooling

Ferron manages FastCGI backend connections using a connection pool. This reduces the overhead of establishing new connections for each request.

fcgi_concurrent_conns

Configuration example:

fcgi_concurrent_conns 8192

Configuration example with no limit:

fcgi_concurrent_conns false

Per-upstream connection limits

When using multiple FastCGI backends, you can set individual connection limits for each:

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        limit 64
    }
}

The limit directive sets the maximum number of concurrent connections for that specific backend.

Environment variables

Ferron automatically sets the following FastCGI environment variables:

Additional variables set by environment directives override any automatically set variables with the same name.

Authentication

When used alongside an authentication module (e.g., http-basicauth), Ferron automatically populates the AUTH_TYPE and REMOTE_USER environment variables in the FastCGI request. The authentication type is extracted from the Authorization header (e.g., Basic or Bearer).

Trace context injection

When a trace context exists for the request, Ferron automatically injects W3C Trace Context headers (traceparent, tracestate, and baggage) into the FastCGI request. These headers are mapped to standard CGI environment variables:

This works in both pass true and pass false modes. The trace context headers are available to the FastCGI backend application, enabling end-to-end distributed tracing. For example, a PHP application running with the official OpenTelemetry SDK for PHP can read these headers to create child spans automatically.

Observability

Logs

• ERROR: logged when a connection to the FastCGI backend fails. The message includes the connection error details.
• WARN: logged when a FastCGI backend produces output on stderr. The message includes the trimmed stderr content.

Structured logs

Metrics

Examples

PHP with PHP-FPM over a Unix socket

example.com {
    root /var/www/html
    fcgi_php "unix:///run/php/php8.4-fpm.sock"
}

PHP with PHP-FPM over TCP

example.com {
    root /var/www/html
    fcgi_php "tcp://127.0.0.1:9000"
}

FastCGI with environment variables

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        environment "APP_ENV" "production"
        environment "APP_SECRET" "{{env.APP_SECRET}}"
    }
}

FastCGI with keepalive and connection limits

example.com {
    fcgi {
        backend tcp://127.0.0.1:9000
        keepalive
        limit 64
        extension ".php"
    }
}

FastCGI with selective file routing

example.com {
    root /var/www/html

    # Only .php files are processed by the FastCGI backend
    fcgi {
        backend tcp://127.0.0.1:9000
        pass false
        extension ".php"
    }

    # Other files are served statically
}