Ferron logo

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.
  • rproxy - this module enables reverse proxy functionality.
  • scgi - this module enables the support for connecting to SCGI servers.

The following modules are built into Ferron, but are disabled by default:

  • asgi - this module enables the support for ASGI web applications.
  • example - this module responds with “Hello World!” for “/hello” request paths.
  • wsgi - this module enables the support for WSGI web applications.
  • wsgid - this module enables the support for WSGI web applications running on a pre-forked worker pool.

Module notes

asgi module

The asgi module runs ASGI applications on a single worker process. Due to Python’s GIL (Global Interpreter Lock), the performance might be lower than what it would be run on multiple worker processes.

This module expects the ASGI application to have application as the ASGI callback. If you’re using some other callback name, you can create the file below (assuming that the callback name is app and the main application Python file is app.py):

from app import app

application = app

This module requires that Ferron links to the Python library.

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.

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

wsgi module

The wsgi module runs WSGI applications on a single worker process. Due to Python’s GIL (Global Interpreter Lock), the performance might be lower than what it would be run on multiple worker processes. If you are using Unix or a Unix-like system, it’s recommended to use the wsgid module instead.

This module expects the WSGI application to have application as the WSGI callback. If you’re using some other callback name, you can create the file below (assuming that the callback name is app and the main application Python file is app.py):

from app import app

application = app

This module requires that Ferron links to the Python library.

wsgid module

The wsgid module runs WSGI applications on a pre-forked process pool. This module can be enabled only on Unix and a Unix-like systems. Additionaly, it’s recommended to stop the processes in the process pool in addition to the main process, as the server will not automatically stop the processes in the process pool (except on Linux systems, where the processes in the process pool are automatically stopped when the server is stopped).

This module expects the WSGI application to have application as the WSGI callback. If you’re using some other callback name, you can create the file below (assuming that the callback name is app and the main application Python file is app.py):

from app import app

application = app

This module requires that Ferron links to the Python library.