Configuration: CGI support

This page documents the cgi directive for configuring Ferron’s CGI (Common Gateway Interface) support. 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"
    }
}

The cgi block can be written as a boolean flag to enable CGI with all defaults, or 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 CGI is enabled and no explicit index directive is configured, Ferron automatically injects default index file names. By default, the following files are checked in order: index.html, index.htm, index.xhtml.

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 only applies when no explicit index directive is set. If you configure your own index directive, Ferron will use that instead.

CGI script locations

A request is handled 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 a matching file is found, Ferron checks for an interpreter using the following priority:

1. Custom interpreter directive matching the file extension.
2. Built-in default interpreter for the extension.
3. If the file is directly executable (has the executable bit on Unix, or is a native .exe on Windows), it is run directly.
4. If the file has a shebang line, the interpreter is parsed 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 a trace context exists for the request, Ferron automatically injects W3C Trace Context headers (traceparent, tracestate, and baggage) into the CGI request. These headers are mapped 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 to create 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

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 PHP files to be handled 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)
}