Configuration: CGI support

This page documents the cgi directive for configuring CGI (Common Gateway Interface) support in Ferron. CGI enables dynamic content by spawning external interpreters for scripts matched by file extension or placed under a cgi-bin directory.

cgi⁠#

example.com {
    cgi {
        extension ".php"
        interpreter ".php" php-cgi -c /etc/php/cgi.ini
        environment "APP_ENV" "production"
    }
}

You can write the cgi block as a boolean flag to enable CGI with all defaults. You can also write it as a block with nested directives to customize behavior.

extension⁠#

Configuration example:

example.com {
    cgi {
        extension ".php"
        extension ".rb"
    }
}

interpreter⁠#

Configuration example:

example.com {
    cgi {
        interpreter ".php" php-cgi -c /etc/php/cgi.ini
        interpreter ".pl" perl
        interpreter ".py" python3
        interpreter ".php" false
    }
}

environment⁠#

Configuration example:

example.com {
    cgi {
        environment "APP_ENV" "production"
        environment "APP_SECRET" "{{env.APP_SECRET}}"
        environment "RUBY_VERSION" "3.3"
    }
}

Default interpreters⁠#

The following built-in interpreters are available when no custom interpreter directive matches:

Default index files⁠#

When you enable CGI and do not set an explicit index directive, Ferron adds default index file names. By default, Ferron checks index.html, index.htm, and index.xhtml in order.

If you register additional extensions via the extension directive, Ferron also prepends corresponding index files to the front of the list:

For example, with extension ".php" configured, the injection order becomes: index.php, index.html, index.htm, index.xhtml.

This injection applies only when you do not set an explicit index directive. With your own index directive, Ferron uses it instead.

CGI script locations⁠#

Ferron treats a request as a CGI script when:

1. The resolved path is inside a cgi-bin directory (case-insensitive match on the first path component after the document root), or
2. The file extension matches one registered via the extension directive.

When Ferron finds a matching file, it looks for an interpreter in this priority:

1. Custom interpreter directive matching the file extension.
2. Built-in default interpreter for the extension.
3. If the file is directly executable (executable bit on Unix, or native .exe on Windows), Ferron runs it directly.
4. If the file has a shebang line, Ferron parses the interpreter from the shebang.

Environment variables⁠#

Ferron automatically sets the following CGI environment variables:

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

Trace context injection⁠#

When the request has a trace context, Ferron injects W3C Trace Context headers into the CGI request. These headers (traceparent, tracestate, and baggage) map to standard CGI environment variables:

This enables end-to-end distributed tracing with CGI scripts. For example, a PHP script running with the official OpenTelemetry SDK for PHP can read these headers. It then creates child spans automatically.

Observability⁠#

Logs⁠#

• WARN: logged when a CGI script exits with a non-zero status and produces output on stderr. The message includes the trimmed stderr content.

Structured logs⁠#

Metrics⁠#

Access log fields⁠#

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

Trace spans⁠#

The CGI stage sets the following attributes on its ferron.stage.cgi span:

Examples⁠#

PHP with a custom PHP-CGI binary⁠#

example.com {
    root /srv/www/example
    cgi {
        extension ".php"
        interpreter ".php" php-cgi -c /etc/php/8.2/cgi/php.ini
    }
}

Multiple interpreters with environment variables⁠#

example.com {
    root /srv/www/app
    cgi {
        extension ".rb"
        interpreter ".rb" ruby
        interpreter ".py" python3
        environment "RUBY_VERSION" "3.3"
        environment "PYTHONUNBUFFERED" "1"
    }
}

Disabling the default PHP interpreter⁠#

example.com {
    root /srv/www/example
    cgi {
        interpreter ".php" false
    }
}

This allows Ferron to handle PHP files via shebang lines or direct execution instead.

Using cgi-bin with additional extensions⁠#

example.com {
    root /srv/www/example

    cgi {
        extension ".php"
        environment "APP_ENV" "production"
    }

    # /srv/www/example/cgi-bin/handler.py is treated as CGI
    # /srv/www/example/scripts/script.php is also treated as CGI
    # (because of the ".php" extension directive)
}