Skip to main content
The file server module is a handler that serves static files from the local filesystem or custom file systems. Module ID: http.handlers.file_server

​
Overview

The file server constructs the path to serve by joining the site root and the sanitized request path. Files within the root and links with targets outside the site root may be accessed.

​
Configuration

​
fs
string
default:"{http.vars.fs}"
The file system implementation to use. By default, Caddy uses the local disk file system.If a non-default filesystem is used, it must first be registered in the globals section.
​
root
string
default:"{http.vars.root}"
The path to the root of the site. Default is {http.vars.root} if set, or current working directory otherwise.
A site root is not a sandbox. Although the file server sanitizes the request URI to prevent directory traversal, files and folders within the root may be directly accessed based on the request path.
​
hide
array of strings
List of files or folders to hide. The file server will pretend they don’t exist. Accepts glob patterns like *.ext or /foo/*/bar.Because site roots can be dynamic, this list uses file system paths, not request paths. The base of relative paths is the current working directory.Examples:
  • hidden - Hides all files/folders named “hidden” anywhere
  • ./hidden - Hides only the “hidden” file/folder in current directory
  • *.secret - Hides all files ending with .secret
​
index_names
array of strings
default:"['index.html', 'index.txt']"
The names of files to try as index files if a folder is requested.
​
browse
object
Enables file listings if a directory was requested and no index file is present.When enabled, the file server may serve a JSON array of the directory listing when the Accept header includes application/json:
[{
  "name": "file.txt",
  "size": 1024,
  "url": "/path/to/file.txt",
  "mod_time": "2024-01-15T10:30:00Z",
  "mode": 420,
  "is_dir": false,
  "is_symlink": false
}]
​
canonical_uris
boolean
default:"true"
Use redirects to enforce trailing slashes for directories or remove them for files.Canonicalization will not happen if the last element of the request’s path (the filename) was changed in an internal rewrite.
​
pass_thru
boolean
default:"false"
If enabled and a requested file is not found, invoke the next handler in the chain instead of returning a 404 error.This is useful for SPAs (Single Page Applications) where you want to serve index.html for any non-existent routes.
​
status_code
string
Override the status code written when successfully serving a file. Useful when explicitly serving a file as an error page display.Supports placeholders. By default, the status code will be 200, or 206 for partial content.

​
Precompressed Files

​
precompressed
module map
Selection of encoders to use to check for precompressed sidecar files.Module namespace: http.precompressed
"precompressed": {
  "gzip": {},
  "br": {}
}
If a request comes in with Accept-Encoding: gzip, and file.txt.gz exists, Caddy will serve the precompressed file with Content-Encoding: gzip.
​
precompressed_order
array of strings
If the client has no strong preference (q-factor), choose encodings in this order.
"precompressed_order": ["br", "gzip"]

​
Etag Configuration

​
etag_file_extensions
array of strings
List of file extensions to try to read Etags from. If set, file Etags will be read from sidecar files with these suffixes, instead of generating our own.Etag values in the files must be quoted as per RFC 7232.
"etag_file_extensions": [".etag", ".md5"]

​
Response Headers

The file server sets the following headers:
  • Etag - Calculated from file modification time and size
  • Last-Modified - File’s modification time
  • Content-Type - Determined from file extension (no MIME sniffing)
  • Content-Encoding - Set if serving precompressed files
  • Vary: Accept-Encoding - Always set for proper caching
The file server properly handles conditional requests with:
  • If-Match
  • If-Unmodified-Since
  • If-Modified-Since
  • If-None-Match
  • Range
  • If-Range

​
Configuration Examples

​
Basic File Server

{
  "handler": "file_server",
  "root": "/var/www/html"
}

​
With Browse Enabled

{
  "handler": "file_server",
  "root": "/var/www/html",
  "browse": {}
}

​
Hiding Files

{
  "handler": "file_server",
  "root": "/var/www/html",
  "hide": [".git", "*.secret", "/config/*"]
}

​
With Precompressed Files

{
  "handler": "file_server",
  "root": "/var/www/html",
  "precompressed": {
    "gzip": {},
    "br": {}
  },
  "precompressed_order": ["br", "gzip"]
}

​
SPA Configuration

{
  "handle": [
    {
      "handler": "file_server",
      "pass_thru": true
    },
    {
      "handler": "rewrite",
      "uri": "/index.html"
    },
    {
      "handler": "file_server"
    }
  ]
}

​
Custom Index Files

{
  "handler": "file_server",
  "root": "/var/www/html",
  "index_names": ["index.html", "index.htm", "default.html"]
}

​
Security Considerations

Important Security Notes:
  1. The site root is not a sandbox. Files within the root can be accessed based on the request path.
  2. On Windows, the file server rejects:
    • Paths with Alternate Data Streams (ADS)
    • Paths with “8.3” short names
  3. Use the hide directive to prevent access to sensitive files
  4. The file server does not perform MIME sniffing on content

​
Path Sanitization

The file server uses path.Clean() to sanitize request paths before joining with the root:
  • Multiple slashes are collapsed
  • Dot elements (. and ..) are resolved and removed
  • Paths are cleaned to prevent directory traversal
For example:
  • /foo/../bar becomes /bar
  • /foo//bar becomes /foo/bar
  • /./foo becomes /foo

​
Etag Calculation

Etags are calculated using: 
"<modification_time_unix_nano_base36><file_size_base36>"
This provides a strong validator for HTTP caching without reading file contents.
The file server uses millisecond-precision modification times (on ext4 and similar filesystems), which qualifies as a strong validator per RFC 9110.

​
Platform-Specific Behavior

​
Windows

On Windows, the file server:
  • Trims trailing dots and spaces from paths (Windows ignores them)
  • Rejects paths with : characters (ADS)
  • Rejects paths with ~ in short segments (8.3 short names)
This prevents security issues where files might be served unintentionally.

​
Error Handling

The file server returns:
  • 404 Not Found - File doesn’t exist (or is hidden)
  • 403 Forbidden - Permission denied
  • 400 Bad Request - Invalid path
  • 503 Service Unavailable - Too many open files (with Retry-After header)
  • 405 Method Not Allowed - Method other than GET/HEAD (except in error context)

Build docs developers (and LLMs) love

Get started for freeTalk to us