Configuration / Sites and static files

Sites and static files

A site is one website, selected by the host name the client asks for. This page shows how to define sites, serve files from a directory, split a site into routes, and control the security headers, compression, rate limits and error pages that go with it.

The smallest static site

server {
    listen ":443"
    listen ":80" redirect-https=#true

    tls {
        acme {
            email "[email protected]"
        }
    }
}

site "example.com" "www.example.com" {
    root "/var/www/example"
}

This passes check --strict. Requests for example.com or www.example.com are answered with files from /var/www/example; a request for a directory gets its index.html. Plain HTTP on port 80 is redirected to HTTPS with 308 Permanent Redirect.

How a request finds its site

List one or more host names after site. Each name may belong to only one site (E107 otherwise). Names are matched without regard to letter case, in this order:

  1. An exact name, such as "www.example.com".
  2. A wildcard "*.example.com". It matches exactly one extra label: shop.example.com, but not example.com and not a.shop.example.com.
  3. If the config has exactly one site, requests for localhost, 127.0.0.1 or ::1 also go to it.

A request for a host that matches no site gets MiraServe's built-in welcome page (status 200) for GET and HEAD, and 405 for other methods. Over HTTPS, if the host in the request differs from the name sent in the TLS handshake (SNI) and either one belongs to a configured site, the answer is 421 Misdirected Request. The redirect listener on port 80 only redirects configured hosts and answers 421 for others, so it cannot be used as an open redirect.

Serving files from a root

root sets the document root: the directory files are served from. All file access is confined to that directory by the operating system (through cap-std), so .. segments and symbolic links cannot reach files outside it. Without any routes, the root is served with these defaults:

  • A directory request serves index.html from that directory.
  • Dotfiles and dot-directories such as .env, .git and .htaccess are refused with 404. The one exception is /.well-known/ at the top level (for files such as security.txt); dotfiles inside it are still refused.
  • Compression is on; see Compression.
  • ETag, conditional requests and byte ranges are supported.

The root must be an absolute path to a dedicated directory. The checker rejects (E202) a relative path, a path containing .., anything under /etc, /root, /proc, /sys, /dev or /boot, and broad shared directories such as /, /var, /var/lib, /tmp, /usr or a whole home directory like /home/alice. Subdirectories such as /var/www/example or /srv/example are fine. See Sandboxing for the full list.

Never point a site root at a PHP application unless the site also has a route "*.php" with fastcgi-pass. MiraServe refuses to hand out .php files as downloads only when a FastCGI route on the same site covers that extension, or when the site uses preset "wordpress-hardened" (which also covers .phtml, .phar and .phps). Otherwise a .php file under the root is a static file like any other, and a request for /wp-config.php returns its source code, including database passwords. See PHP and WordPress.

Routes

A route sends part of a site to a specific handler. Routes are checked in the order you write them, and the first match wins. A request that matches no route falls back to the site root, or gets 404 if there is none.

site "example.com" {
    root "/var/www/example"

    route "/downloads/*" {
        root "/srv/downloads"
        rate-limit requests=30 per="1m" burst=10
        static {
            index "index.html" "README.txt"
            compression #false
        }
    }

    route "/app/*" {
        try-files "{path}" "/app/index.html"
    }
}

Route patterns come in four forms. Anything else is rejected with E301:

PatternMatches
"/about"Exactly /about.
"/docs/*"/docs and everything below /docs/, but not /docsearch.
"/*"Every path.
"*.php"Every path whose file name ends in .php, in any letter case.

Put specific routes before broad ones. A route that can never match because an earlier route already catches all its requests produces warning W014. Note that "/*" catches everything, including *.php paths, so route "*.php" must come before route "/*".

Each route has exactly one handler (E302 otherwise): static, try-files, fastcgi-pass (PHP and WordPress), reverse-proxy (Reverse proxy), mcp-gateway (MCP gateway) or wasm-plugin (WASM plugins). A route may also set its own root, rate-limit and security-headers. static, try-files and fastcgi-pass need a root on the route or the site (E303).

try-files

try-files tries a list of candidate paths in order and serves the first file that exists. It is the usual way to give a single-page application or a CMS a fallback. In each candidate, {path} is replaced by the request path and {query} by the query string.

  • A candidate ending in /, such as "{path}/", looks for a directory and its index file.
  • A candidate of the form "=404" stops and answers with that status code.
  • The last candidate is not tested for existence. MiraServe internally rewrites the request to it: if a FastCGI route matches the new path, PHP handles it; otherwise it is served as a static file.

Candidates whose extension belongs to a FastCGI route are never served as files.

Security headers

security-headers chooses which protective response headers MiraServe adds. It can be set on a site and overridden on a route. These are the exact headers sent:

Header"strict" (default)"standard"
Strict-Transport-Security (HTTPS only)max-age=63072000; includeSubDomainsmax-age=31536000; includeSubDomains
X-Content-Type-Optionsnosniffnosniff
Referrer-Policystrict-origin-when-cross-originstrict-origin-when-cross-origin
X-Frame-OptionsDENYSAMEORIGIN
Cross-Origin-Opener-Policysame-originnot sent
Permissions-Policygeolocation=(), microphone=(), camera=()not sent
Values from a backend or PHPreplaced by the values abovekept; the values above fill in only missing headers

"off" sends none of these and produces warning W004. Use it only when something in front of MiraServe adds equivalent headers. Every policy keeps the Server: MiraServe header and, on HTTPS listeners with HTTP/3, an Alt-Svc header.

No Content-Security-Policy is sent for your content. None of the policies or presets adds a Content-Security-Policy header to your pages, and MiraServe has no directive for adding custom response headers. You must set your own: from the application behind a reverse proxy or FastCGI route, or, for a static site, with a <meta http-equiv="Content-Security-Policy" content="…"> tag in each HTML page. (MiraServe's own built-in error and welcome pages do carry a restrictive policy.)

includeSubDomains tells browsers to use HTTPS for every subdomain of the site's host for up to two years (strict) or one year (standard). Make sure all subdomains can serve HTTPS before you deploy.

Presets

preset adds a fixed set of request checks to a site. They run before routes. Blocked requests are logged with the rule name.

PresetWhat it blocks
"static-strict"Methods other than GET, HEAD and OPTIONS (405); . and .. segments or NUL bytes (400); dotfiles except a top-level /.well-known/ (404); backup files ending in ~, .bak, .old, .orig, .swp or .sql (404).
"api-gateway". and .. segments or NUL bytes (400); dotfiles except a top-level /.well-known/ (404).
"wordpress-hardened"See PHP and WordPress.

Compression

Static files are compressed according to the client's Accept-Encoding header, preferring zstd, then br, then gzip:

  • If a precompressed copy exists next to the file (app.js.zst, app.js.br or app.js.gz), it is sent.
  • Otherwise, text-like files (text/*, JavaScript, JSON, XML, SVG, WebAssembly and feeds) between 1 KiB and 4 MiB are compressed on the fly with br or gzip. zstd is only used from precompressed files.

To turn this off for a route, use compression #false inside its static block.

Rate limits

A rate limit allows a steady number of requests per period plus a short burst above it. When a client goes over, it gets 429 Too Many Requests with a Retry-After header.

site "example.com" {
    root "/var/www/example"
    rate-limit requests=600 per="1m" burst=100 key="client-ip"
}

A site limit is checked first, then the limit of the matching route. key chooses what is counted separately: "client-ip" (default; IPv6 clients are grouped by /64), "agent-id" (the identity of a bot verified through the site's bot-auth block), or "header:<name>" such as "header:x-api-key". The client IP is the address of the TCP connection; MiraServe does not read X-Forwarded-For from incoming requests.

Error pages

MiraServe answers errors with built-in pages: HTML for browsers, plain text for other clients. You can replace them per site and per status code:

site "example.com" {
    root "/var/www/example"

    error-pages {
        login-url "/login"
        page 404 "errors/404.html"
        page 503 "/srv/shared/maintenance.html"
    }
}
  • page takes a status code from 400 to 599 and a file. A relative path is read from inside the site root (and needs one, E202 otherwise); an absolute path is read when the config is loaded or reloaded. Files may be up to 512 KiB.
  • login-url is the link used by the Sign in button on the built-in 401 page. It must be a path starting with / or an https:// URL (http:// works but gives W019).

Reference

site

DirectiveDefaultMeaning
rootnoneDocument root for static files.
security-headers"strict""strict", "standard" or "off".
presetnone"static-strict", "api-gateway" or "wordpress-hardened".
rate-limitnonerequests= (required), per= (required), burst= (defaults to requests), key= (defaults to "client-ip").
tls { … }nonePer-site TLS; see TLS and certificates.
error-pages { … }built-in pageslogin-url and page <status> <file>.
route "<pattern>" { … }noneMay repeat. Matched in order.
bot-auth, ai-publishnoneSee Publishing.

A site needs at least one of root, ai-publish or a route (E006).

static (inside a route)

DirectiveDefaultMeaning
index"index.html"One or more index file names, tried in order.
dotfiles"deny""deny" or "allow". "allow" gives W008.
compression#trueContent-encoding negotiation and on-the-fly compression.

static can be written without a block (static on its own line) to use all defaults.

Pitfalls

  • PHP source exposure. A root that contains .php files and no *.php FastCGI route serves those files as plain downloads. See the warning above.
  • Catch-all first. route "/*" before any other route makes the others unreachable (W014).
  • No CSP by default. Strict headers do not include a Content-Security-Policy. Add your own.
  • Behind a CDN or load balancer. Rate limits by "client-ip" see the address of the proxy in front, so all visitors share one bucket. Use a header key set by your proxy, or apply limits at the proxy.
  • Unknown hosts get a page. Requests for host names you did not configure receive the welcome page, not an error. Point DNS only at hosts you serve.