Server configuration properties

Ferron can be configured in the ferron.yaml file. Below is the description of configuration properties for this server.

Global-only configuration properties

• port (u16 or String)
  • HTTP port or address-port combination for the server to listen. This is the primary port on which the server will accept incoming HTTP connections. Default: 80
• sport (u16 or String)
  • HTTPS port or address-port combination for the server to listen. This is the primary port on which the server will accept incoming HTTPS connections. Default: 443
• secure (bool)
  • Option to enable HTTPS. When set to true, the server will use HTTPS for secure communication. Default: false
• http2Settings (Object)
  • HTTP/2 settings. This object contains various settings related to HTTP/2 protocol configuration. Default: None
  • Sub-properties:
    • initialWindowSize (u32)
      • Initial window size for HTTP/2. This setting controls the initial flow control window size for HTTP/2 connections. Default: None
    • maxFrameSize (u32)
      • Maximum frame size for HTTP/2. This setting determines the largest frame payload that the server will accept. Default: None
    • maxConcurrentStreams (u32)
      • Maximum number of concurrent streams for HTTP/2. This setting limits the number of concurrent streams that can be open at any given time. Default: None
    • maxHeaderListSize (u32)
      • Maximum header list size for HTTP/2. This setting controls the maximum size of the header list that the server will accept. Default: None
    • enableConnectProtocol (bool)
      • Enable the HTTP/2 CONNECT protocol. When set to true, the server will support the CONNECT method for tunneling TCP connections. Default: false
• logFilePath (String)
  • Path to the log file. This setting specifies the file path where the server will write its logs. The logs written by Ferron use Combined Log Format. Default: None
• errorLogFilePath (String)
  • Path to the error log file. This setting specifies the file path where the server will write its error logs. Default: None
• enableHTTP2 (bool)
  • Option to enable HTTP/2. When set to true, the server will support the HTTP/2 protocol. Default: true
• cert (String)
  • Path to the TLS certificate. This setting specifies the file path to the TLS certificate used for HTTPS connections. Default: None
• key (String)
  • Path to the private key. This setting specifies the file path to the private key associated with the TLS certificate. Default: None
• sni (Object)
  • SNI certificate and key data. This object contains the certificate and key data for Server Name Indication (SNI), which allows multiple SSL certificates to be used on the same IP address. The object keys are SNI hostnames, while the object values are objects where certificates and private keys can be specified. Default: None
  • Sub-properties:
    • cert (String)
      • Path to the SNI certificate. This setting specifies the file path to the SNI certificate. Default: None
    • key (String)
      • Path to the SNI private key. This setting specifies the file path to the private key associated with the SNI certificate. Default: None
• loadModules (Array<String>)
  • Modules to load. This setting specifies an array of modules that the server should load at startup. The module handlers are executed in order of the list of modules to load defined in this property (for example if cache module is first specified, and then fcgi, then the cache module handler will be first executed, then fcgi). Default: None
• useClientCertificate (bool)
  • Option to require client to provide its certificate. When set to true, the server will require clients to present a valid certificate for authentication. Default: false
• cipherSuite (Array<String>)
  • A list of cipher suites. This setting specifies an array of cipher suites that the server will support for encrypted connections. Default: None
• ecdhCurve (Array<String>)
  • A list of ECDH curves. This setting specifies an array of elliptic curves that the server will support for ECDH key exchanges. Default: None
• tlsMinVersion (String)
  • Minimum TLS version (TLSv1.2 or TLSv1.3). This setting specifies the minimum version of TLS that the server will accept. Default: "TLSv1.2"
• tlsMaxVersion (String)
  • Maximum TLS version (TLSv1.2 or TLSv1.3). This setting specifies the maximum version of TLS that the server will accept. Default: "TLSv1.3"
• disableNonEncryptedServer (bool)
  • Option to disable the HTTP server if the HTTPS server is running. When set to true, the server will only accept HTTPS connections and will disable the HTTP server. Default: false
• blocklist (Array<String>)
  • IP block list. This setting specifies an array of IP addresses that the server will block from accessing its services. The block list will only work with non-forward proxy requests. Default: None
• enableOCSPStapling (bool)
  • Option to enable OCSP stapling. When set to true, the server will use OCSP stapling to provide certificate revocation status to clients. Certificates with Must-Staple extension will not work with automatic TLS enabled. Default: true
• environmentVariables (Object)
  • Environment variables. This object contains environment variables that the server will use during operation. Default: None
• enableAutomaticTLS (bool)
  • Option to enable automatic TLS through Let’s Encrypt. The automatic TLS will use an TLS-ALPN-01 ACME challenge. The domain names for the certificate will be extracted from the host configuration (wildcard domains are ignored, since TLS-ALPN-01 ACME challenge doesn’t support them). The automatic TLS will work when the HTTPS port is set to 443. Default: false
• automaticTLSContactEmail (String)
  • The email address used by automatic TLS for an account in Let’s Encrypt. This email address can be used to send notifications by Let’s Encrypt. Default: None
• automaticTLSContactCacheDirectory (String)
  • The path to the directory used by automatic TLS to store cache data, such as cached certificates. Default: None
• automaticTLSLetsEncryptProduction (bool)
  • Option to enable production Let’s Encrypt ACME endpoint. If set to false, the staging Let’s Encrypt ACME endpoint will be used. Default: true
• loadBalancerHealthCheckWindow (u32; rproxy module)
  • A window (in milliseconds) between each failed connection report made by a load balancer. Default: 5000
• timeout (u32 or null)
  • A maximum time (in milliseconds) for server to process the request, after which the server resets the connection. If set to null, the timeout is disabled. It’s not recommended to disable the timeout, as disabling it may leave the server vulnerable to Slow HTTP attacks. Default: 300000
• maximumCacheEntries (u32 or null; cache module)
  • Maximum amount of cache entries that can be stored in the cache. If set to null, the cache can theoretically store unlimited entries. The cache keys for entries depend on the request method, the request URL, the “Host” header value, and varying request headers. Default: null
• useAutomaticTLSHTTPChallenge (bool; Ferron 1.1.0 and newer)
  • Option to enable HTTP-based ACME challenge for automatic TLS. When set to true, the server will use the HTTP-01 ACME challenge instead of TLS-ALPN-01 one. Default: false
• enableHTTP3 (bool; Ferron 1.1.0 and newer)
  • Option to enable HTTP/3. When set to true, the server will support the HTTP/3 protocol. Currently, HTTP/3 support is experimental. The TLS_AES_128_GCM_SHA256 needs to be enabled, otherwise HTTP/3 server wouldn’t start at all. Default: false
• wsgiClearModuleImportPath (bool; wsgi module; Ferron 1.1.0 and newer)
  • Option to enable clearing Python module import paths. Setting this option to true improves the compatiblity with setups involving multiple WSGI applications, however module imports inside functions must not be used in the WSGI application. Default: false
• asgiClearModuleImportPath (bool; asgi module; Ferron 1.1.0 and newer)
  • Option to enable clearing Python module import paths. Setting this option to true improves the compatiblity with setups involving multiple ASGI applications, however module imports inside functions must not be used in the ASGI application. Default: false

Host configuration properties

• locations (Array<Object>)
  • The list of locations specified for a specific host. The sub-properties of this property will be merged in combined server configuration. The URLs will not be rewritten. To rewrite the URLs, configure the URL rewrite map in location configuration. Default: None

Location configuration properties

• path (String)
  • The path specified for a location. The location is matched against URL-decoded request URL. If it is the same, or the decoded request URL are levels above the specified path, the location configuration will be used. Default: None

Global, host & location configuration properties

• domain (String)
  • The domain name of a host. This setting specifies the domain name associated with the host. Default: None
• ip (String)
  • The IP address of a host. This setting specifies the IP address associated with the host. Default: None
• serverAdministratorEmail (String)
  • Server administrator’s email address. This setting specifies the email address of the server administrator, which may be used for contact purposes. Default: None
• customHeaders (Object)
  • Custom HTTP headers. This object contains custom HTTP headers that the server will include in its responses. You can also use the {path} placeholder that will be replaced by the request URL in the custom HTTP header values. Default: None
• disableToHTTPSRedirect (bool)
  • Option to disable redirects from the HTTP server to the HTTPS server. When set to true, the server will not automatically redirect HTTP requests to HTTPS. Default: false
• wwwredirect (bool)
  • Option to enable redirects to domain name that begins with “www.”. When set to true, the server will automatically redirect requests to the “www” subdomain. Default: false
• enableIPSpoofing (bool)
  • Option to enable identifying client’s originating IP address through the X-Forwarded-For header. When set to true, the server will use the X-Forwarded-For header to identify the client’s IP address. Default: false
• allowDoubleSlashes (bool)
  • Option to allow double slashes in URL sanitizer. When set to true, the server will allow double slashes in URLs, which may be useful for certain types of URL rewriting. Default: false
• rewriteMap (Array<Object>)
  • URL rewrite map. This setting specifies an array of URL rewrite rules that the server will apply to incoming requests. Default: None
  • Sub-properties:
    • regex (String)
      • Regular expression for URL rewriting. This setting specifies the regular expression pattern that the server will use to match URLs for rewriting. Default: None
    • replacement (String)
      • Replacement string for URL rewriting. This setting specifies the replacement string that the server will use to rewrite matched URLs. Default: None
    • isNotFile (bool)
      • Option to apply the rule only if the path is not a file. When set to true, the server will only apply the rewrite rule if the path does not correspond to a file. Default: false
    • isNotDirectory (bool)
      • Option to apply the rule only if the path is not a directory. When set to true, the server will only apply the rewrite rule if the path does not correspond to a directory. Default: false
    • allowDoubleSlashes (bool)
      • Option to allow double slashes in the rewritten URL. When set to true, the server will allow double slashes in the rewritten URL. Default: false
    • last (bool)
      • Option to stop processing further rules after this one. When set to true, the server will stop processing further rewrite rules after this one. Default: false
• enableRewriteLogging (bool)
  • Option to enable logging of URL rewrites. When set to true, the server will log all URL rewrites that it performs. Default: false
• wwwroot (String)
  • Webroot from which static files will be served. This setting specifies the root directory from which the server will serve static files. Default: None
• disableTrailingSlashRedirects (bool)
  • Option to disable redirects if the path points to a directory. When set to true, the server will not automatically redirect requests to a trailing slash if the path points to a directory. Default: false
• users (Array<Object>)
  • User list. This setting specifies an array of user objects that the server will use for authentication. It’s recommended to use the ferron-passwd tool to generate the user objects. Default: None
  • Sub-properties:
    • user (String)
      • Username. This setting specifies the username for a user. Default: None
    • pass (String)
      • Password hash. This setting specifies the hashed password for a user. Default: None
• nonStandardCodes (Array<Object>)
  • Non-standard status codes. This setting specifies an array of non-standard HTTP status codes that the server will use for specific responses. Default: None
  • Sub-properties:
    • scode (u16)
      • Status code. This setting specifies the non-standard HTTP status code. If set to 401, HTTP basic authentication is enabled (users are specified in users configuration property). Default: None
    • url (String)
      • URL to match or redirect to. This setting specifies the URL pattern that the server will use to match requests or the URL to which the server will redirect requests. Default: None
    • regex (String)
      • Regular expression to match the URL. This setting specifies the regular expression pattern that the server will use to match URLs. Default: None
    • location (String)
      • Redirect location. This setting specifies the location to which the server will redirect requests. Default: None
    • realm (String)
      • Realm for basic authentication. This setting specifies the realm that the server will use for basic authentication. Default: None
    • disableBruteProtection (bool)
      • Option to disable brute force protection. When set to true, the server will disable brute force protection for the specified status code. Default: false
    • userList (Array<String>)
      • List of users allowed to access. This setting specifies an array of usernames that are allowed to access the resource associated with the status code. Default: None
    • users (Array<String>)
      • List of IP addresses allowed to access. This setting specifies an array of IP addresses that are allowed to access the resource associated with the status code. Default: None
• errorPages (Array<Object>)
  • Custom error pages. This setting specifies an array of custom error pages that the server will use for specific HTTP status codes. Default: None
  • Sub-properties:
    • scode (u16)
      • Status code. This setting specifies the HTTP status code for which the custom error page will be used. Default: None
    • path (String)
      • Path to the error page. This setting specifies the file path to the custom error page. Default: None
• enableETag (bool)
  • Option to enable ETag generation. When set to true, the server will generate ETag headers for responses, which can be used for caching purposes. Default: true
• enableCompression (bool)
  • Option to enable HTTP compression. When set to true, the server will compress responses using gzip or other compression algorithms to reduce bandwidth usage. Default: true
• enableDirectoryListing (bool)
  • Option to enable directory listings. When set to true, the server will generate and display a list of files and directories when a directory is requested. Default: false
• proxyTo (String or Array<String>; rproxy module)
  • Base URL, which reverse proxy will send requests to. HTTP and HTTPS URLs are supported. It’s also possible to specify an array of base URLs (requests will be randomly distributed). Default: None
• secureProxyTo (String or Array<String>; rproxy module)
  • Base URL, which reverse proxy will send requests to, if the client is connected via HTTPS. HTTP and HTTPS URLs are supported. It’s also possible to specify an array of base URLs (requests will be randomly distributed). Default: None
• cacheVaryHeaders (Array<String>; cache module)
  • A list of request headers that can vary in a cache. Supplements the “Vary” response header. Default: None
• cacheIgnoreHeaders (Array<String>; cache module)
  • A list of response headers that will not be stored in a cache. Default: None
• maximumCacheResponseSize (u64 or null; cache module)
  • A maximum response size to be cached in bytes. If null, the maximum response size is unlimited theoretically. Default: null
• cgiScriptExtensions (Array<String>; cgi module)
  • CGI script extensions, which will be handled via CGI handler outside the cgi-bin directory. Default: None
• cgiScriptInterpreters (Object; cgi module)
  • CGI script interpreters used by the CGI handler. The object keys represent the extension, for which a specific interpreter is used, while object values can be either an Array<String> representing first arguments of the CGI script (the first argument is the path to the interpreter), or null for removing the default interpreter. Default: None, the default interpreterss are set for .pl, .py, .sh, .ksh, .csh, .rb and .php extensions, and addtionally .exe, .bat and .vbs extensions for Windows.
• scgiTo (String; scgi module)
  • Base URL, which SCGI client will send requests to. TCP (for example "tcp://localhost:4000/") and Unix socket URLs (only on Unix systems; for example "unix:///run/scgi.sock") are supported. Default: "tcp://localhost:4000/"
• scgiPath (String; scgi module)
  • Base URL, which SCGI client will handle the request if the request URL begins with it. If not specified, the SCGI client will be inactive. Default: None
• fcgiScriptExtensions (Array<String>; fcgi module)
  • FastCGI script extensions, which will be handled via FastCGI handler outside the specified FastCGI path. Default: None
• fcgiTo (String; fcgi module)
  • Base URL, which FastCGI client will send requests to. TCP (for example "tcp://localhost:4000/") and Unix socket URLs (only on Unix systems; for example "unix:///run/fcgi.sock") are supported. Default: "tcp://localhost:4000/"
• fcgiPath (String; fcgi module)
  • Base URL, which FastCGI client will handle the request if the request URL begins with it. If not specified, the SCGI client will be inactive. Default: None
• authTo (String; fauth module)
  • Base URL, which web server will send requests to for forwarded authentication. HTTP and HTTPS URLs are supported. Default: None
• forwardedAuthCopyHeaders (Array<String>; fauth module)
  • A list of response headers that will be copied from the forwarded authentication server response to the original request. Default: None
• enableLoadBalancerHealthCheck (u32; rproxy module)
  • Option to enable passive health checks for the load balancer. If the connection by the load balancer fails, the load balancer notes the failed connection, and if there are too many of them, the load balancer temporarily marks the backend server as “bad” and will not choose the backend server. Default: false
• loadBalancerHealthCheckMaximumFails (u32; rproxy module)
  • Maximum reported failed connections, before a backend server is marked as “bad” and not chosen by the load balancer. Default: 3
• disableProxyCertificateVerification (bool; rproxy module)
  • Option to disable backend server certificate verification for the reverse proxy. Setting this to true is not recommended for production use. Default: false
• wsgiApplicationPath (String; wsgi module; Ferron 1.1.0 and newer)
  • Path to the file containing the WSGI application. The WSGI application must have an application WSGI callback. Default: None
• wsgiPath (String; wsgi module; Ferron 1.1.0 and newer)
  • Base URL, which WSGI handler will handle the request if the request URL begins with it. Default: "/"
• wsgidApplicationPath (String; wsgid module; Ferron 1.1.0 and newer)
  • Path to the file containing the WSGI application. The WSGI application must have an application WSGI callback. Default: None
• wsgidPath (String; wsgid module; Ferron 1.1.0 and newer)
  • Base URL, which WSGI handler (with pre-forked process pool) will handle the request if the request URL begins with it. Default: "/"
• asgiApplicationPath (String; asgi module; Ferron 1.1.0 and newer)
  • Path to the file containing the ASGI application. The ASGI application must have an application ASGI callback. Default: None
• asgiPath (String; asgi module; Ferron 1.1.0 and newer)
  • Base URL, which ASGI handler will handle the request if the request URL begins with it. Default: "/"

Server configuration includes

Server configuration includes can be specified in the include section in the server configuration (at the same level as global and host would have). The include section is a list of glob patterns that match the configuration file names to be merged.

Example configuration

Below is the example Ferron web server configuration:

global:
  port: 8080
  sport: 8443
  secure: true
  enableHTTP2: true
  http2Settings:
    initialWindowSize: 65536
    maxFrameSize: 16384
    maxConcurrentStreams: 100
    maxHeaderListSize: 8192
    enableConnectProtocol: true
  logFilePath: "/var/log/ferron/access.log"
  errorLogFilePath: "/var/log/ferron/error.log"
  cert: "/etc/ssl/certs/fallback.crt"
  key: "/etc/ssl/private/fallback.key"
  tlsMinVersion: "TLSv1.2"
  tlsMaxVersion: "TLSv1.3"
  disableNonEncryptedServer: false
  enableOCSPStapling: true
  blocklist:
    - "192.168.1.100"
    - "10.0.0.5"
  enableCompression: true
  enableDirectoryListing: false
  environmentVariables:
    APP_MODE: "production"
    MAX_THREADS: "16"
  loadModules:
    - "rproxy"
  sni:
    "example.com": 
      cert: "/etc/ssl/certs/example-com.crt"
      key: "/etc/ssl/private/example-com.key"
    "*.example.com": 
      cert: "/etc/ssl/certs/example-com.crt"
      key: "/etc/ssl/private/example-com.key"

hosts:
  - domain: "example.com"
    serverAdministratorEmail: "admin@example.com"
    wwwredirect: true
    customHeaders:
      X-Frame-Options: "DENY"
      X-Content-Type-Options: "nosniff"
    rewriteMap:
      - regex: "^/old-path/(.*)"
        replacement: "/new-path/$1"
        isNotFile: true
        isNotDirectory: true
        last: true
    wwwroot: "/var/www/example"
    errorPages:
      - scode: 404
        path: "/var/www/example/errors/404.html"
      - scode: 500
        path: "/var/www/example/errors/500.html"
    locations:
      - path: "/static"
        wwwroot: "/var/www/static"
        rewriteMap:
          - regex: "^/static(?:[/?#](.*))?"
            replacement: "/$1"
            last: true
  - domain: "api.example.com"
    serverAdministratorEmail: "api-admin@example.com"
    disableToHTTPSRedirect: false
    allowDoubleSlashes: false
    enableETag: true
    users:
      - user: "admin"
        pass: "$2b$10$hashedpassword12345"
    nonStandardCodes:
      - scode: 401
        url: "/restricted.html"
    proxyTo: "http://backend-service:5000"
# # Uncomment to enable configuration file includes
#include:
#  - /etc/ferron.d/**/*.yaml