Server modules

You can extend Ferron with modules written in Rust.

The following modules are built into Ferron and are enabled by default:

cache - this module enables server response caching.
cgi - this module enables the execution of CGI programs.
fauth - this module enables authentication forwarded to the authentication server.
fcgi - this module enables the support for connecting to FastCGI servers.
fproxy - this module enables forward proxy functionality.
limit (Ferron 2.0.0-beta.2 and newer) - this module enables rate limits.
replace (Ferron 2.0.0-beta.2 and newer) - this module enables replacement of strings in response bodies.
rproxy - this module enables reverse proxy functionality.
scgi - this module enables the support for connecting to SCGI servers.
static (Ferron 2.0.0-beta.1 and newer) - this module enables static file serving.

Ferron also supports additional modules that can be enabled at compile-time.

Additional modules provided by Ferron are from these repositories:

ferron-modules-python - provides gateway interfaces (ASGI, WSGI) utilizing Python.
ferron-module-example - responds with “Hello World!” for “/hello” request paths.

If you would like to use Ferron with additional modules, you can check the compilation notes.

Module notes

cache module

The cache module is a simple in-memory cache module for Ferron that works with “Cache-Control” and “Vary” headers. The cache is shared across all threads.

cgi module

To run PHP scripts with this module, you may need to adjust the PHP configuration file, typically located at /etc/php/<php version>/cgi/php.ini, by setting the cgi.force_redirect property to 0. If you don’t make this change, PHP-CGI will show a warning indicating that the PHP-CGI binary was compiled with force-cgi-redirect enabled. It is advisable to use directories outside of cgi-bin for user uploads and downloads to prevent the cgi module from mistakenly treating uploaded scripts with shebangs and ELF binary files as CGI applications, which could lead to issues such as malware infections, remote code execution vulnerabilities, or 500 Internal Server Errors.

fauth module

This module is inspired by Traefik’s ForwardAuth middleware. If the authentication server replies with a 2xx status code, access is allowed, and the initial request is executed. If not, the response from the authentication server is sent back.

The following request headers are provided to the authentication server:

X-Forwarded-Method - the HTTP method used by the original request
X-Forwarded-Proto - if the original request is encrypted, it’s "https", otherwise it’s "http".
X-Forwarded-Host - the value of the Host header from the original request
X-Forwarded-Uri - the original request URI
X-Forwarded-For - the client’s IP address

fcgi module

PHP-FPM may run on different user than Ferron, so you might need to set permissions for the PHP-FPM user.

If you are using PHP-FPM only for Ferron, you can set the listen.owner and listen.group properties to the Ferron user in the PHP-FPM pool configuration file (e.g. /etc/php/8.2/fpm/pool.d/www.conf).

fproxy module

If you are using the fproxy module, then hosts on the local network and local host are also accessible from the proxy. You may block these using a firewall, if you don’t want these hosts to be accessible from the proxy.

limit module

This module uses a Token Bucket algorithm. The rate limitation is on per-IP address basis.

replace module

If you’re using this module with static file serving, it’s recommended to disable static file compression using compressed #false, otherwise the replacement wouldn’t work.

rproxy module

The reverse proxy functionality is enabled when proxyTo or secureProxyTo configuration property is specified.

The following request headers are provided to the backend server:

X-Forwarded-Proto - if the original request is encrypted, it’s "https", otherwise it’s "http".
X-Forwarded-Host - the value of the Host header from the original request
X-Forwarded-For - the client’s IP address