Configuration: static file serving

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

Directives

Index and directory listings

• index <filename: string>...
  • This directive specifies one or more filenames to try when a request path resolves to a directory. Files are tried in order; the first existing file replaces the directory path in the file context. Only applies 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 specifies whether auto-generated HTML directory listings are enabled when a request path resolves to a directory and no index file is found. 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 specifies whether ETag generation for static file responses is enabled. ETags are weak ETags (W/"...") generated 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. The value is passed 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. Multiple mime_type directives can be used 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 specifies one or more HTTP status codes followed by a file path to serve 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, {{trace.id}} and {{trace.spanid}} in the error page file are replaced with the request’s trace ID and span ID. 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 symbolic links are allowed during file path resolution. When a symlink is encountered while traversing the request path, the behavior depends on this setting:
    • false (default): Allow all symlinks without restriction.
    • true: Reject all symbolic links with a 403 Forbidden response. Symlinks are detected during path traversal without following them, mitigating symlink-based escape attacks.
    • "if_not_owner": Allow symlinks only if owned by the same user as the target file (Unix only; treated as true on non-Unix systems).
  • Default: disable_symlinks false

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, backward compatible)
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 for at most 200 milliseconds after the first request. This is done by caching file metadata and the open file handle in memory. The cache is keyed by the file path and is invalidated when the file is modified, deleted, or replaced.

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

The following best-practice check is reported by ferron doctor for directives on this page.

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