Configuration: static file serving

This page documents directives that configure static file serving, directory listings, compression, caching behavior, and custom error pages. These directives apply to requests that resolve to the filesystem (via root).

Directives⁠#

Web root⁠#

• root <path: string>
  • This directive specifies the webroot that the HTTP file-handler pipeline uses after regular HTTP stages leave the request without a response. Ferron canonicalizes the resolved path before file stages run. Ferron rejects requests that try to escape the webroot. Default: not configured

Configuration example:

example.com {
    root /srv/www/example
}

Index and directory listings⁠#

• index <filename: string>...
  • This directive specifies one or more filenames to try when a request path resolves to a directory. Ferron tries them in order. The first existing file replaces the directory path in the file context. This applies only when the resolved path is a directory and no path_info is present. Default: index index.html index.htm index.xhtml
• directory_listing [bool: boolean] (http-static)
  • This directive controls whether Ferron auto-generates an HTML listing when a request path resolves to a directory. Ferron generates a listing only when no index file exists. Default: directory_listing false

Configuration example:

example.com {
    root /srv/www/example
    index index.html index.htm
    directory_listing
}

Caching headers⁠#

• etag [bool: boolean] (http-static)
  • This directive controls whether Ferron generates ETags for static file responses. Ferron uses weak ETags (W/"...") and derives them from an xxHash3 hash of the file path, size, and modification time. Default: etag true
• file_cache_control <value: string> (http-static)
  • This directive specifies the Cache-Control response header for all static file responses. Ferron passes the value through as-is. Default: not set

Configuration example:

example.com {
    root /srv/www/example
    etag
    file_cache_control "public, max-age=3600"
}

MIME types⁠#

• mime_type <extension: string> <mime-type: string> (http-static)
  • This directive maps a file extension (with or without leading dot) to a MIME type. Custom MIME type mappings override the built-in database for matching extensions. You can use multiple mime_type directives to map different extensions. Default: built-in MIME database

Configuration example:

example.com {
    root /srv/www/example
    mime_type ".wasm" "application/wasm"
    mime_type ".webmanifest" "application/manifest+json"
}

Error pages⁠#

• error_page <status-code: integer>... <file-path: string>
  • This directive maps one or more HTTP status codes to a file path. Ferron serves that file as the error response body. The last argument is always the file path. All preceding arguments are status codes. Default: built-in error pages
• error_page_placeholders [bool: boolean]
  • When enabled, Ferron replaces {{trace.id}} and {{trace.spanid}} in the error page file. It uses the trace ID and span ID of the request. Default: false

Configuration example:

example.com {
    root /srv/www/example
    error_page 404 /custom/404.html
    error_page 500 502 503 504 /custom/50x.html
    error_page_placeholders true
}

Symlink handling⁠#

• disable_symlinks [bool: boolean | string: "if_not_owner"]
  • This directive controls whether Ferron allows symbolic links during file path resolution. When the resolver encounters a symlink while traversing the request path, the behavior depends on this setting:
    • false: Allow all symlinks without restriction.
    • true (default): Reject all symbolic links with a 403 Forbidden response. The resolver detects symlinks during path traversal without following them, mitigating symlink-based escape attacks.
    • "if_not_owner": Allow symlinks when the same user owns the link and the target file. On non-Unix systems, Ferron treats this value as true.
  • Default: disable_symlinks true

Configuration example:

example.com {
    root /srv/www/example
    disable_symlinks
}

# Allow symlinks only in a specific virtual host
uploads.example.com {
    root /srv/uploads
    disable_symlinks if_not_owner
}

# Allow symlinks (default)
legacy.example.com {
    root /srv/www/legacy
    disable_symlinks false
}

File handle reuse⁠#

Ferron reuses file handles (and I/O errors) for static file responses to reduce file I/O overhead. The reuse lasts at most 200 milliseconds after the first request.

Observability⁠#

Metrics⁠#

Static file serving⁠#

Access log fields⁠#

The static file serving module and the file resolution stage contribute the following fields to the HTTP access log line:

Trace spans⁠#

The file resolution span (ferron.pipeline.file_resolve) captures the resolution process before any file-serving stage runs:

The static file stage sets the following attributes on its ferron.stage.static_file span:

The directory listing stage sets the following attributes on its ferron.stage.directory_listing span:

Best practices⁠#

ferron doctor reports the following best-practice check for the directives on this page.

• directory_listing enabled: Auto-generated directory indexes expose file structure. Enable only for intentionally public file listings.