Configuration: FastCGI support

This page documents the fcgi directive, which configures FastCGI support in Ferron. FastCGI enables dynamic content by forwarding requests to external application servers over TCP or Unix sockets. It also supports connection pooling and keepalive.

fcgi⁠#

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

The fcgi directive enables FastCGI protocol support. You can write it as a boolean flag to enable with defaults. You can write a backend URL to set the target. You can also write it as a block with nested directives to customize behavior. Ferron supports configuring multiple FastCGI backends using multiple fcgi or fcgi_php directives.

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 an 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.

This directive would be (roughly) equivalent to the following configuration:

example.com {
    root /var/www/html
    fcgi {
        backend tcp://php:9000/ # <-- Backend URL
        pass false
        extension ".php"
        # Other subdirectives...
    }
    index index.php index.html index.htm
}

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 that environment directives define override any variables with the same name.

Authentication⁠#

When used alongside an authentication module (for example, http-basicauth), Ferron automatically populates the AUTH_TYPE and REMOTE_USER environment variables in the FastCGI request. Ferron extracts the authentication type from the Authorization header (for example, 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. Ferron maps these headers to standard CGI environment variables:

This works in both pass true and pass false modes. The FastCGI backend application can read the trace context headers. This enables end-to-end distributed tracing. For example, a PHP application can use the official OpenTelemetry SDK for PHP to read these headers. The application creates 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⁠#

Access log fields⁠#

The FastCGI module contributes the following fields to the HTTP access log line:

Trace spans⁠#

The FastCGI stage sets the following attributes on its ferron.stage.fcgi_pass span:

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
}